Endpoints | Developers

Fetch a basket by its identifier

get

Gets the basket associated with the provided identifier.

Authorizations

Path parameters

identstringRequired

The basket identifier.

Example: 1a-55fff4107740a1f40d844ff89607557f45bfafb3

Responses

200

Successful response returns the basket. The `links.payment` property is only returned if the basket has been paid for, and a payment exist with the **complete**/**refund**/**chargeback** status. The `links.checkout` property is only returned if the basket has not been paid, and is the URL to send the customer to in order to complete payment.

application/json

404

Basket not found.

get

GET /api/baskets/{ident} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*

{
  "ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
  "expire": "2022-10-25 15:15:40",
  "price": 1.27,
  "priceDetails": {
    "fullPrice": 1.4,
    "subTotal": 1.27,
    "discounts": [],
    "total": 1.4,
    "surcharges": [],
    "tax": 0.13,
    "balance": 0,
    "sales": [],
    "giftcards": [],
    "roundUp": null
  },
  "isPaymentMethodUpdate": false,
  "returnUrl": null,
  "complete": false,
  "tax": 1,
  "username": null,
  "discounts": [
    {}
  ],
  "coupons": [
    {}
  ],
  "giftcards": [
    {}
  ],
  "address": {
    "name": "Ted Tebex",
    "first_name": "Ted",
    "last_name": "Tebex",
    "address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
    "email": "[email protected]",
    "state_id": null,
    "country": "UK",
    "postal_code": "NW6 3QT"
  },
  "rows": [
    {
      "id": 173125385,
      "basket": 725572301,
      "package": null,
      "override": 0,
      "quantity": 2,
      "server": null,
      "price": 1.27,
      "gift_username_id": null,
      "options": null,
      "recurring": false,
      "recurring_period": null,
      "recurring_next_payment_date": null,
      "meta": {
        "name": "1000 Gold",
        "rowprice": 2.54,
        "initialprice": 1.27,
        "isCumulative": false,
        "requiredPackages": [],
        "requiresAny": false,
        "category": false,
        "producesGiftCard": false,
        "allowsGiftCards": true,
        "servers": [],
        "limits": {
          "user": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "global": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "packageExpiryTime": 0
        },
        "hasDeliverables": false,
        "deliverableTypes": [],
        "downloadLink": "",
        "hasSellerProtection": true,
        "itemType": null,
        "revenue_share": [],
        "image": null,
        "realprice": 1.27
      },
      "custom": null,
      "image_url": null,
      "recurring_price": null
    }
  ],
  "fingerprint": "",
  "creator_code": "text",
  "roundup": false,
  "cancel_url": "https://tebex.io",
  "complete_url": null,
  "complete_auto_redirect": false,
  "custom": {
    "foo": "bar",
    "ref": 1234
  },
  "links": {
    "payment": "https://checkout.tebex.io/api/payments/tbx-12345",
    "checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
  }
}

Create a basket that can be used to pay for items

post

This will create and return a Basket that can be paid for by redirecting the user to links.checkout

Authorizations

Body

return_urlstringOptional

The URL a customer can return to without completing checkout

Example: https://example.tebex.io/

complete_urlstringOptional

URL the customer can return to after completing payment

Example: https://example.tebex.io/complete

customobjectOptional

Any custom data to be passed through the request. This will be returned in a post-completion webhook.

Example: {"foo":"bar"}

first_namestringOptional

The first name of the customer

Example: Neil

last_namestringOptional

The last name of the customer

Example: McNeil

emailstringOptional

The email address of the customer

Example: [email protected]

expires_atstringOptional

An ISO8601 formatted date. After this date the basket cannot be used to checkout.

Example: 2025-01-27T18:09:51Z

complete_auto_redirectbooleanOptional

Automatically redirect to the complete_url provided

Example: true

countrystringOptional

An ISO 3166-1 alpha-2 character code representing the customer's country.

Example: US

creator_codestringOptional

The creator code is used to share a percentage of the payment with another party. See more about creator codes at https://docs.tebex.io/creators/tebex-control-panel/engagement/creator-codes

ipstringOptional

The IP address of the customer using this basket. Provide the IP if creating a basket on your server backend.

Example: 1.2.3.4

Responses

200

Basket created successfully

application/json

post

POST /api/baskets HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 300

{
  "return_url": "https://example.tebex.io/",
  "complete_url": "https://example.tebex.io/complete",
  "custom": {
    "foo": "bar"
  },
  "first_name": "Neil",
  "last_name": "McNeil",
  "email": "[email protected]",
  "expires_at": "2025-01-27T18:09:51Z",
  "complete_auto_redirect": true,
  "country": "US",
  "creator_code": null,
  "ip": "1.2.3.4"
}

200

Basket created successfully

{
  "ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
  "expire": "2022-10-25 15:15:40",
  "price": 1.27,
  "priceDetails": {
    "fullPrice": 1.4,
    "subTotal": 1.27,
    "discounts": [],
    "total": 1.4,
    "surcharges": [],
    "tax": 0.13,
    "balance": 0,
    "sales": [],
    "giftcards": [],
    "roundUp": null
  },
  "isPaymentMethodUpdate": false,
  "returnUrl": null,
  "complete": false,
  "tax": 1,
  "username": null,
  "discounts": [
    {}
  ],
  "coupons": [
    {}
  ],
  "giftcards": [
    {}
  ],
  "address": {
    "name": "Ted Tebex",
    "first_name": "Ted",
    "last_name": "Tebex",
    "address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
    "email": "[email protected]",
    "state_id": null,
    "country": "UK",
    "postal_code": "NW6 3QT"
  },
  "rows": [
    {
      "id": 173125385,
      "basket": 725572301,
      "package": null,
      "override": 0,
      "quantity": 2,
      "server": null,
      "price": 1.27,
      "gift_username_id": null,
      "options": null,
      "recurring": false,
      "recurring_period": null,
      "recurring_next_payment_date": null,
      "meta": {
        "name": "1000 Gold",
        "rowprice": 2.54,
        "initialprice": 1.27,
        "isCumulative": false,
        "requiredPackages": [],
        "requiresAny": false,
        "category": false,
        "producesGiftCard": false,
        "allowsGiftCards": true,
        "servers": [],
        "limits": {
          "user": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "global": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "packageExpiryTime": 0
        },
        "hasDeliverables": false,
        "deliverableTypes": [],
        "downloadLink": "",
        "hasSellerProtection": true,
        "itemType": null,
        "revenue_share": [],
        "image": null,
        "realprice": 1.27
      },
      "custom": null,
      "image_url": null,
      "recurring_price": null
    }
  ],
  "fingerprint": "",
  "creator_code": "text",
  "roundup": false,
  "cancel_url": "https://tebex.io",
  "complete_url": null,
  "complete_auto_redirect": false,
  "custom": {
    "foo": "bar",
    "ref": 1234
  },
  "links": {
    "payment": "https://checkout.tebex.io/api/payments/tbx-12345",
    "checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
  }
}

Add a package to the basket

post

This adds a package (an object describing the product) to the basket {ident}. For subscriptions, only one subscription item may be in a basket at a time, and it cannot be included with one-time payment items. This endpoint requires prior approval. Please contact your account manager.

Authorizations

Path parameters

identstringRequired

The basket identifier.

Example: 1a-55fff4107740a1f40d844ff89607557f45bfafb3

Body

qtyintegerOptional

The quantity of package in this basket. This is not the total quantity of overall items in the basket.

Example: 2

typestring · enumOptional

The type of payment, either single for one-time payments or subscription.

Example: singlePossible values:

Responses

200

Package is successfully added to the basket, and basket is returned.

application/json

400

Improperly formatted package. See ErrorResponse.

404

Basket not found.

post

POST /api/baskets/{ident}/packages HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 260

{
  "package": {
    "name": "1000 Gold",
    "price": 1.27,
    "type": "subscription",
    "qty": 1,
    "expiry_period": "month",
    "expiry_length": 3,
    "custom": {
      "foo": "bar"
    }
  },
  "qty": 2,
  "type": "single",
  "revenue_share": [
    {
      "wallet_ref": "centralised_404244_127",
      "amount": 0.5,
      "gateway_fee_percent": 50
    }
  ]
}

{
  "ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
  "expire": "2022-10-25 15:15:40",
  "price": 1.27,
  "priceDetails": {
    "fullPrice": 1.4,
    "subTotal": 1.27,
    "discounts": [],
    "total": 1.4,
    "surcharges": [],
    "tax": 0.13,
    "balance": 0,
    "sales": [],
    "giftcards": [],
    "roundUp": null
  },
  "isPaymentMethodUpdate": false,
  "returnUrl": null,
  "complete": false,
  "tax": 1,
  "username": null,
  "discounts": [
    {}
  ],
  "coupons": [
    {}
  ],
  "giftcards": [
    {}
  ],
  "address": {
    "name": "Ted Tebex",
    "first_name": "Ted",
    "last_name": "Tebex",
    "address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
    "email": "[email protected]",
    "state_id": null,
    "country": "UK",
    "postal_code": "NW6 3QT"
  },
  "rows": [
    {
      "id": 173125385,
      "basket": 725572301,
      "package": null,
      "override": 0,
      "quantity": 2,
      "server": null,
      "price": 1.27,
      "gift_username_id": null,
      "options": null,
      "recurring": false,
      "recurring_period": null,
      "recurring_next_payment_date": null,
      "meta": {
        "name": "1000 Gold",
        "rowprice": 2.54,
        "initialprice": 1.27,
        "isCumulative": false,
        "requiredPackages": [],
        "requiresAny": false,
        "category": false,
        "producesGiftCard": false,
        "allowsGiftCards": true,
        "servers": [],
        "limits": {
          "user": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "global": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "packageExpiryTime": 0
        },
        "hasDeliverables": false,
        "deliverableTypes": [],
        "downloadLink": "",
        "hasSellerProtection": true,
        "itemType": null,
        "revenue_share": [],
        "image": null,
        "realprice": 1.27
      },
      "custom": null,
      "image_url": null,
      "recurring_price": null
    }
  ],
  "fingerprint": "",
  "creator_code": "text",
  "roundup": false,
  "cancel_url": "https://tebex.io",
  "complete_url": null,
  "complete_auto_redirect": false,
  "custom": {
    "foo": "bar",
    "ref": 1234
  },
  "links": {
    "payment": "https://checkout.tebex.io/api/payments/tbx-12345",
    "checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
  }
}

Remove a row from the basket

delete

This will remove the given {rows.id} from the basket {ident}. The basket must be re-fetched after running to receive updated totals.

Authorizations

Path parameters

identstringRequired

The basket identifier.

Example: 1a-55fff4107740a1f40d844ff89607557f45bfafb3

rows.idintegerRequired

The id of the basket.rows row to remove.

Example: 1

Responses

204

Successfully deleted a row from the basket.

404

Row or basket not found.

delete

DELETE /api/baskets/{ident}/packages/{rows.id} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*

No content

Add a sale to the basket

post

Adds a Sale to the basket with {ident}. Sales cannot be applied to baskets with revenue_share set.

Authorizations

Path parameters

identstringRequired

The basket identifier.

Example: 1a-55fff4107740a1f40d844ff89607557f45bfafb3

Body

namestringOptional

The name of the sale (displayed to the customer)

Example: Test Sale

discount_typestring · enumOptional

The type of discount, either percentage for deducting a percentage of each item, or amount to deduct a fixed amount from each item.

Example: amountPossible values:

amountnumberOptional

The amount or percentage to deduct

Example: 4.99

Responses

200

Successfully adds sale to basket.

application/json

400

Bad request. Improperly formatted Sale or this basket cannot accept sales. See ErrorResponse.

404

Basket not found.

post

POST /api/baskets/{ident}/sales HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "name": "Test Sale",
  "discount_type": "amount",
  "amount": 4.99
}

{
  "ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
  "expire": "2022-10-25 15:15:40",
  "price": 1.27,
  "priceDetails": {
    "fullPrice": 1.4,
    "subTotal": 1.27,
    "discounts": [],
    "total": 1.4,
    "surcharges": [],
    "tax": 0.13,
    "balance": 0,
    "sales": [],
    "giftcards": [],
    "roundUp": null
  },
  "isPaymentMethodUpdate": false,
  "returnUrl": null,
  "complete": false,
  "tax": 1,
  "username": null,
  "discounts": [
    {}
  ],
  "coupons": [
    {}
  ],
  "giftcards": [
    {}
  ],
  "address": {
    "name": "Ted Tebex",
    "first_name": "Ted",
    "last_name": "Tebex",
    "address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
    "email": "[email protected]",
    "state_id": null,
    "country": "UK",
    "postal_code": "NW6 3QT"
  },
  "rows": [
    {
      "id": 173125385,
      "basket": 725572301,
      "package": null,
      "override": 0,
      "quantity": 2,
      "server": null,
      "price": 1.27,
      "gift_username_id": null,
      "options": null,
      "recurring": false,
      "recurring_period": null,
      "recurring_next_payment_date": null,
      "meta": {
        "name": "1000 Gold",
        "rowprice": 2.54,
        "initialprice": 1.27,
        "isCumulative": false,
        "requiredPackages": [],
        "requiresAny": false,
        "category": false,
        "producesGiftCard": false,
        "allowsGiftCards": true,
        "servers": [],
        "limits": {
          "user": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "global": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "packageExpiryTime": 0
        },
        "hasDeliverables": false,
        "deliverableTypes": [],
        "downloadLink": "",
        "hasSellerProtection": true,
        "itemType": null,
        "revenue_share": [],
        "image": null,
        "realprice": 1.27
      },
      "custom": null,
      "image_url": null,
      "recurring_price": null
    }
  ],
  "fingerprint": "",
  "creator_code": "text",
  "roundup": false,
  "cancel_url": "https://tebex.io",
  "complete_url": null,
  "complete_auto_redirect": false,
  "custom": {
    "foo": "bar",
    "ref": 1234
  },
  "links": {
    "payment": "https://checkout.tebex.io/api/payments/tbx-12345",
    "checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
  }
}

Create a checkout request

post

This API call allows the complete checkout flow (create basket, add items, add sale) to be made in a single API call, for when the Seller is managing the basket locally. This endpoint requires prior approval - please contact your account manager.

Authorizations

Body

Responses

200

Successfully created basket. The basket will be returned with `links` containing the URLs you should direct the customer to in order to complete payment.

application/json

400

Bad Request. See ErrorResponse.

post

POST /api/checkout HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 330

{
  "basket": {
    "first_name": "Neil",
    "last_name": "McNeil",
    "email": "[email protected]",
    "return_url": "https://tebex.io",
    "complete_url": "https://tebex.io",
    "custom": {
      "foo": "bar",
      "trackingId": 127,
      "list": [
        "1",
        "2",
        "3"
      ]
    }
  },
  "items": [
    {
      "package": {
        "price": 1.27,
        "name": "1000 Gold"
      }
    }
  ],
  "sale": {
    "name": "Test Sale",
    "discount_type": "amount",
    "amount": 4.99
  }
}

{
  "ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
  "expire": "2022-10-25 15:15:40",
  "price": 1.27,
  "priceDetails": {
    "fullPrice": 1.4,
    "subTotal": 1.27,
    "discounts": [],
    "total": 1.4,
    "surcharges": [],
    "tax": 0.13,
    "balance": 0,
    "sales": [],
    "giftcards": [],
    "roundUp": null
  },
  "isPaymentMethodUpdate": false,
  "returnUrl": null,
  "complete": false,
  "tax": 1,
  "username": null,
  "discounts": [
    {}
  ],
  "coupons": [
    {}
  ],
  "giftcards": [
    {}
  ],
  "address": {
    "name": "Ted Tebex",
    "first_name": "Ted",
    "last_name": "Tebex",
    "address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
    "email": "[email protected]",
    "state_id": null,
    "country": "UK",
    "postal_code": "NW6 3QT"
  },
  "rows": [
    {
      "id": 173125385,
      "basket": 725572301,
      "package": null,
      "override": 0,
      "quantity": 2,
      "server": null,
      "price": 1.27,
      "gift_username_id": null,
      "options": null,
      "recurring": false,
      "recurring_period": null,
      "recurring_next_payment_date": null,
      "meta": {
        "name": "1000 Gold",
        "rowprice": 2.54,
        "initialprice": 1.27,
        "isCumulative": false,
        "requiredPackages": [],
        "requiresAny": false,
        "category": false,
        "producesGiftCard": false,
        "allowsGiftCards": true,
        "servers": [],
        "limits": {
          "user": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "global": {
            "enabled": false,
            "timestamp": 0,
            "limit": false
          },
          "packageExpiryTime": 0
        },
        "hasDeliverables": false,
        "deliverableTypes": [],
        "downloadLink": "",
        "hasSellerProtection": true,
        "itemType": null,
        "revenue_share": [],
        "image": null,
        "realprice": 1.27
      },
      "custom": null,
      "image_url": null,
      "recurring_price": null
    }
  ],
  "fingerprint": "",
  "creator_code": "text",
  "roundup": false,
  "cancel_url": "https://tebex.io",
  "complete_url": null,
  "complete_auto_redirect": false,
  "custom": {
    "foo": "bar",
    "ref": 1234
  },
  "links": {
    "payment": "https://checkout.tebex.io/api/payments/tbx-12345",
    "checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
  }
}

Fetch a payment by its transaction ID

get

This will fetch the given payment associated with this transaction id. Single payment transaction IDs begin with tbx-

Authorizations

Path parameters

txnIdstringRequired

The payment reference to fetch.

Example: tbx-55fff4107740a1f40d844ff89607557f45bfafb3

Responses

200

Payment fetched successfully.

application/json

404

Transaction not found.

get

GET /api/payments/{txnId} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*

{
  "transaction_id": "tbx-26929122a56954-0e15be",
  "status": {
    "id": 1,
    "description": "Complete"
  },
  "payment_sequence": "oneoff",
  "created_at": "2022-10-19T15:49:15.000000Z",
  "price": {
    "amount": 5.35,
    "currency": "USD"
  },
  "fees": {
    "tax": {
      "amount": 0,
      "currency": "USD"
    },
    "gateway": {
      "amount": 0.45,
      "currency": "USD"
    }
  },
  "customer": {
    "first_name": "Test",
    "last_name": "Test",
    "email": "[email protected]",
    "ip": "1.2.3.4",
    "username": "text",
    "marketing_consent": false,
    "country": "TS",
    "postal_code": "text"
  },
  "products": [
    {
      "id": "text",
      "name": "text",
      "quantity": 1,
      "base_price": {
        "amount": 1,
        "currency": "text"
      },
      "paid_price": {
        "amount": 1,
        "currency": "text"
      },
      "variables": [
        "text"
      ],
      "expires_at": "2025-07-23T05:27:43.151Z",
      "custom": {},
      "username": "text"
    }
  ],
  "coupons": [
    {}
  ],
  "gift_cards": [
    {}
  ],
  "recurring_payment_reference": "text",
  "custom": {}
}

Refund a payment by its transaction ID

post

This will refund the given payment associated with this transaction id.

Authorizations

Path parameters

txnIdstringRequired

The payment reference to refund.

Example: tbx-55fff4107740a1f40d844ff89607557f45bfafb3

Responses

200

Payment refunded successfully. The payment details are returned.

application/json

404

Payment not found.

422

The payment cannot be refunded. Payments can only be refunded when a payment's `status` is Completed.

post

POST /api/payments/{txnId}/refund HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*

{
  "transaction_id": "tbx-26929122a56954-0e15be",
  "status": {
    "id": 1,
    "description": "Complete"
  },
  "payment_sequence": "oneoff",
  "created_at": "2022-10-19T15:49:15.000000Z",
  "price": {
    "amount": 5.35,
    "currency": "USD"
  },
  "fees": {
    "tax": {
      "amount": 0,
      "currency": "USD"
    },
    "gateway": {
      "amount": 0.45,
      "currency": "USD"
    }
  },
  "customer": {
    "first_name": "Test",
    "last_name": "Test",
    "email": "[email protected]",
    "ip": "1.2.3.4",
    "username": "text",
    "marketing_consent": false,
    "country": "TS",
    "postal_code": "text"
  },
  "products": [
    {
      "id": "text",
      "name": "text",
      "quantity": 1,
      "base_price": {
        "amount": 1,
        "currency": "text"
      },
      "paid_price": {
        "amount": 1,
        "currency": "text"
      },
      "variables": [
        "text"
      ],
      "expires_at": "2025-07-23T05:27:43.151Z",
      "custom": {},
      "username": "text"
    }
  ],
  "coupons": [
    {}
  ],
  "gift_cards": [
    {}
  ],
  "recurring_payment_reference": "text",
  "custom": {}
}

Fetch a recurring payment (subscription) by its reference

get

Authorizations

Path parameters

referencestringRequired

The recurring payment reference to fetch.

Example: tbx-r-55fff4107740a1f40d844ff89607557f45bfafb3

Responses

200

Successfully fetched recurring payment.

application/json

404

Recurring payment not found.

get

GET /api/recurring-payments/{reference} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*

{
  "id": 5000,
  "created_at": "2022-12-16T16:43:06.000000Z",
  "updated_at": "2022-12-16T16:43:06.000000Z",
  "paused_at": "2025-07-23T05:27:43.151Z",
  "paused_until": "2025-07-23T05:27:43.151Z",
  "next_payment_date": "2022-12-30T16:43:06",
  "reference": "88",
  "account_id": 1,
  "interval": "P2W",
  "cancelled_at": "2025-07-23T05:27:43.151Z",
  "cancellation_requested_at": "2024-07-25 14:01:03",
  "status": {
    "id": 2,
    "class": "success",
    "description": "Active",
    "active": 1
  },
  "amount": {
    "amount": 7,
    "tax": 1.4,
    "period": "P2W"
  },
  "cancel_reason": "text",
  "links": {
    "initial_payment": "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id",
    "payment_history": [
      "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id"
    ]
  }
}

Update a subscription with a new product / amount to pay - replacing the existing product

put

If the new subscription amount is higher than the existing amount, a pro-rata charge will be made to cover the cost of the new price up until the next billing date.

This endpoint requires prior approval - please contact your account manager.

Authorizations

Path parameters

referencestringRequired

The recurring payment reference to fetch.

Example: tbx-r-55fff4107740a1f40d844ff89607557f45bfafb3

Body

Responses

200

Successfully updated subscription. The updated `RecurringPayment` is returned.

application/json

400

Bad Request.

404

Recurring payment not found.

put

PUT /api/recurring-payments/{reference} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 201

{
  "items": [
    {
      "type": "subscription",
      "qty": 1,
      "revenue_share": [],
      "package": {
        "name": "1000 Gold",
        "price": 1.27,
        "type": "subscription",
        "qty": 1,
        "expiry_period": "month",
        "expiry_length": 3,
        "custom": {
          "foo": "bar"
        }
      }
    }
  ]
}

{
  "id": 5000,
  "created_at": "2022-12-16T16:43:06.000000Z",
  "updated_at": "2022-12-16T16:43:06.000000Z",
  "paused_at": "2025-07-23T05:27:43.151Z",
  "paused_until": "2025-07-23T05:27:43.151Z",
  "next_payment_date": "2022-12-30T16:43:06",
  "reference": "88",
  "account_id": 1,
  "interval": "P2W",
  "cancelled_at": "2025-07-23T05:27:43.151Z",
  "cancellation_requested_at": "2024-07-25 14:01:03",
  "status": {
    "id": 2,
    "class": "success",
    "description": "Active",
    "active": 1
  },
  "amount": {
    "amount": 7,
    "tax": 1.4,
    "period": "P2W"
  },
  "cancel_reason": "text",
  "links": {
    "initial_payment": "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id",
    "payment_history": [
      "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id"
    ]
  }
}

Cancel a recurring payment

delete

This cancels the recurring payment for the reference provided. Recurring payment references start with tbx-r-

Authorizations

Path parameters

referencestringRequired

The recurring payment reference to cancel.

Example: tbx-r-55fff4107740a1f40d844ff89607557f45bfafb3

Responses

200

Recurring payment cancelled successfully.

application/json

404

Recurring payment not found.

delete

DELETE /api/recurring-payments/{reference} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*

{
  "id": 5000,
  "created_at": "2022-12-16T16:43:06.000000Z",
  "updated_at": "2022-12-16T16:43:06.000000Z",
  "paused_at": "2025-07-23T05:27:43.151Z",
  "paused_until": "2025-07-23T05:27:43.151Z",
  "next_payment_date": "2022-12-30T16:43:06",
  "reference": "88",
  "account_id": 1,
  "interval": "P2W",
  "cancelled_at": "2025-07-23T05:27:43.151Z",
  "cancellation_requested_at": "2024-07-25 14:01:03",
  "status": {
    "id": 2,
    "class": "success",
    "description": "Active",
    "active": 1
  },
  "amount": {
    "amount": 7,
    "tax": 1.4,
    "period": "P2W"
  },
  "cancel_reason": "text",
  "links": {
    "initial_payment": "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id",
    "payment_history": [
      "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id"
    ]
  }
}

Pause or reactivate a recurring payment

put

Authorizations

Path parameters

referencestringRequired

The recurring payment reference to update.

Example: tbx-r-55fff4107740a1f40d844ff89607557f45bfafb3

Body

statusstring · enumRequired

Your desired state of the recurring payment. Provide Paused with paused_until to pause a recurring payment. Otherwise, provide Active to resume a recurring payment.

Example: PausedPossible values:

paused_untilstringOptional

To pause a payment, provide a ISO8601 formatted date on which the payment should be reactivated.

Example: 2025-01-27T16:43:53.000000Z

Responses

200

Successfully paused or reactivated a payment. The `RecurringPayment` is returned.

application/json

404

Recurring payment not found.

422

Unprocessible Entity. An invalid status was provided or the recurring payment cannot be processed. See ErrorResponse.

put

PUT /api/recurring-payments/{reference}/status HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "status": "Paused",
  "paused_until": "2025-01-27T16:43:53.000000Z"
}

{
  "id": 5000,
  "created_at": "2022-12-16T16:43:06.000000Z",
  "updated_at": "2022-12-16T16:43:06.000000Z",
  "paused_at": "2025-07-23T05:27:43.151Z",
  "paused_until": "2025-07-23T05:27:43.151Z",
  "next_payment_date": "2022-12-30T16:43:06",
  "reference": "88",
  "account_id": 1,
  "interval": "P2W",
  "cancelled_at": "2025-07-23T05:27:43.151Z",
  "cancellation_requested_at": "2024-07-25 14:01:03",
  "status": {
    "id": 2,
    "class": "success",
    "description": "Active",
    "active": 1
  },
  "amount": {
    "amount": 7,
    "tax": 1.4,
    "period": "P2W"
  },
  "cancel_reason": "text",
  "links": {
    "initial_payment": "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id",
    "payment_history": [
      "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id"
    ]
  }
}