Subscriptions

Recurring orders.

GET `/subscriptions`

Subscriptions

Scope: orders:read, or the broad read. Newest first, by id.

Parameters

Name	Where	Description
`cursor`	query	`meta.next_cursor` from the previous page. Up to 1024 characters.
`limit`	query	Page size. Above 100 is treated as 100. At least 1. Default `25`.
`role`	query	One of `buyer`, `seller`. Default `buyer`.
`status`	query	One of `0`, `1`.
`If-None-Match`	header	An ETag from an earlier response.

Example request

curl "https://www.seoclerk.com/api/v1/subscriptions" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

Field	Type	Description
`id`	integer
`buyer_id`	integer
`seller_id`	integer or null
`service_id`	integer
`order_id`	integer or null
`amount`	money
`interval_days`	integer
`payment_count`	integer
`status`	integer	1 active, 0 cancelled.
`starts_at`	timestamp or null
`renewed_at`	timestamp or null
`created_at`	timestamp or null

{
    "data": [
        {
            "id": 1024,
            "buyer_id": 1024,
            "seller_id": 1024,
            "service_id": 1024,
            "order_id": 1024,
            "amount": {
                "amount": "12.50",
                "currency": "USD"
            },
            "interval_days": 1,
            "payment_count": 1,
            "status": 1,
            "starts_at": "2026-10-10T14:03:22Z",
            "renewed_at": "2026-10-10T14:03:22Z",
            "created_at": "2026-10-10T14:03:22Z"
        }
    ],
    "meta": {
        "limit": 1,
        "next_cursor": "string",
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
422	`bad_cursor` `invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`

GET `/subscriptions/gateway`

Older gateway-managed subscriptions

Scope: orders:read, or the broad read. Newest first, by id.

Parameters

Name	Where	Description
`cursor`	query	`meta.next_cursor` from the previous page. Up to 1024 characters.
`limit`	query	Page size. Above 100 is treated as 100. At least 1. Default `25`.
`role`	query	One of `buyer`, `seller`. Default `buyer`.
`status`	query	One of `0`, `1`.
`If-None-Match`	header	An ETag from an earlier response.

Example request

curl "https://www.seoclerk.com/api/v1/subscriptions/gateway" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

Field	Type	Description
`id`	integer
`active`	boolean
`last_payment_amount`	money
`payment_at`	timestamp or null

{
    "data": [
        {
            "id": 1024,
            "active": true,
            "last_payment_amount": {
                "amount": "12.50",
                "currency": "USD"
            },
            "payment_at": "2026-10-10T14:03:22Z"
        }
    ],
    "meta": {
        "limit": 1,
        "next_cursor": "string",
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
422	`bad_cursor` `invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`

GET `/subscriptions/gateway/{id}`

An older gateway-managed subscription

Scope: orders:read, or the broad read.

Parameters

Name	Where	Description
`id` required	path	At least 1.
`If-None-Match`	header	An ETag from an earlier response.

Example request

curl "https://www.seoclerk.com/api/v1/subscriptions/gateway/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

Field	Type	Description
`id`	integer
`active`	boolean
`last_payment_amount`	money
`payment_at`	timestamp or null

{
    "data": {
        "id": 1024,
        "active": true,
        "last_payment_amount": {
            "amount": "12.50",
            "currency": "USD"
        },
        "payment_at": "2026-10-10T14:03:22Z"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
422	`invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`

GET `/subscriptions/{id}`

A subscription

Scope: orders:read, or the broad read. Its subscriber or its seller.

Parameters

Name	Where	Description
`id` required	path	At least 1.
`If-None-Match`	header	An ETag from an earlier response.

Example request

curl "https://www.seoclerk.com/api/v1/subscriptions/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

Field	Type	Description
`id`	integer
`buyer_id`	integer
`seller_id`	integer or null
`service_id`	integer
`order_id`	integer or null
`amount`	money
`interval_days`	integer
`payment_count`	integer
`status`	integer	1 active, 0 cancelled.
`starts_at`	timestamp or null
`renewed_at`	timestamp or null
`created_at`	timestamp or null

{
    "data": {
        "id": 1024,
        "buyer_id": 1024,
        "seller_id": 1024,
        "service_id": 1024,
        "order_id": 1024,
        "amount": {
            "amount": "12.50",
            "currency": "USD"
        },
        "interval_days": 1,
        "payment_count": 1,
        "status": 1,
        "starts_at": "2026-10-10T14:03:22Z",
        "renewed_at": "2026-10-10T14:03:22Z",
        "created_at": "2026-10-10T14:03:22Z"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
422	`invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`

POST `/subscriptions/{id}/cancel`

Cancel a subscription

Scope: subscriptions:write, or the broad write. Its subscriber, or the seller of the service. Idempotency-Key is required.

Orders already placed are untouched. The other party is emailed.

Parameters

Name	Where	Description
`id` required	path	At least 1.
`Idempotency-Key` required	header	Makes a retry safe. Required on every POST. Must match `^[A-Za-z0-9_.-]{1,64}$`.

Example request

curl -X POST "https://www.seoclerk.com/api/v1/subscriptions/1024/cancel" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: cancelsubscription-1"

Response 200

Field	Type	Description
`id`	integer
`status`	integer	Always 0.
`cancelled_by`	string
`cancelled_at`	timestamp or null

{
    "data": {
        "id": 1024,
        "status": 1,
        "cancelled_by": "subscriber",
        "cancelled_at": "2026-10-10T14:03:22Z"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`bad_json` `https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
409	`already_cancelled` `idempotency_conflict` `idempotency_in_progress`
413	`body_too_large`
415	`unsupported_media_type`
422	`bad_idempotency_key` `idempotency_key_required` `invalid_fields` `invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`
503	`write_storage_unavailable`

Subscriptions

GET /subscriptions

Parameters

Example request

Response 200

Errors

GET /subscriptions/gateway

Parameters

Example request

Response 200

Errors

GET /subscriptions/gateway/{id}

Parameters

Example request

Response 200

Errors

GET /subscriptions/{id}

Parameters

Example request

Response 200

Errors

POST /subscriptions/{id}/cancel

Parameters

Example request

Response 200

Errors

GET `/subscriptions`

GET `/subscriptions/gateway`

GET `/subscriptions/gateway/{id}`

GET `/subscriptions/{id}`

POST `/subscriptions/{id}/cancel`