API conventions

The Vipter API follows the conventions of Stripe's API wherever there is an equivalent: field names, error format, cursor pagination, idempotency and date-based versions. Anyone who has integrated Stripe will recognize everything. This page gathers what applies to every endpoint; each endpoint is in the reference.

Base URLCopy Anchor Link

https://api.vipter.com/v1

The same service answers at https://app.vipter.com/api/v1, with the same paths. Use api.vipter.com in new integrations; the other address exists for networks where only the dashboard's domain is allowed.

Every call is HTTPS. A URL outside /v1 or a path that does not exist gets 404 resource_missing, in the same format as the other errors.

VersionCopy Anchor Link

The API has date-based versions. The current version is 2026-11-01, the only one that exists today.

Each API key is born pinned to the current version on the day it was created, and requests with it use that version without saying anything. To ask for another version on a call, send the header:

Vipter-Version: 2026-11-01

An unknown version gets 400 invalid_api_version, with the list of accepted versions in the message. Every authenticated response carries the Vipter-Version header with the version used.

Within a version, the API only changes in compatible ways: new fields may appear in any object at any time, and new values may appear in text fields such as status and payment_method. Write your code to ignore fields it does not know. An incompatible change, such as renaming or removing a field, becomes a new version, and existing keys stay on the old one.

Request formatCopy Anchor Link

Query parameters go in the query string. Request bodies, on the endpoints that take one, may be JSON or a form:

The form format uses Stripe's bracket notation: a[b]=1 becomes an object, a[0]=x&a[1]=y or a[]=x&a[]=y become a list. A curl copied from Stripe's documentation works as is. In a form every value arrives as text; the API converts numbers and booleans where it expects them.

The query string accepts the same bracket notation. A body with another Content-Type, or JSON that is not an object, gets 400 parameter_invalid.

Response formatCopy Anchor Link

Every response is JSON in UTF-8, with Cache-Control: no-store. Retrieving an object returns the object; a listing returns a list object (see Pagination); an error returns an error object (see Errors).

Headers present on every response:

Data typesCopy Anchor Link

The metadata, client_reference_id and checkout_session fields of orders and subscriptions come filled in when the sale was born from a checkout session created through the API; on other sales, they come {} or null.

ErrorsCopy Anchor Link

An error is a response with a 4xx or 5xx HTTP status and this body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid query parameter 'limit': Number must be less than or equal to 100",
    "param": "limit",
    "doc_url": "https://docs.vipter.com/pt-br/developers/api-conventions#erros"
  }
}

Error typesCopy Anchor Link

CodesCopy Anchor Link

An object that exists but belongs to another store is a 404, the same as a nonexistent ID. The codes specific to one endpoint, such as offer_unavailable or portal_disabled, are in the reference, next to the endpoint.

IdempotencyCopy Anchor Link

Repeating a request because of a network timeout must not charge twice. For that, every POST and DELETE accepts the Idempotency-Key header, with a unique value you generate, such as a UUID v4:

curl -X POST https://api.vipter.com/v1/… \
  -H "Authorization: Bearer vk_live_…" \
  -H "Idempotency-Key: 5f0b2c8e-3a1d-4e7f-9b6c-2d4a8e1f0c3b" \
  …

The rules, the same as Stripe's:

• The key is valid for 24 hours within the store. Up to 255 characters.
• The same key with the same method, path and body returns the stored response from the first time, with the same HTTP status, without executing anything again. The replayed response carries Idempotent-Replayed: true and Original-Request-Id with the first request's Request-Id.
• The same key with a different body gets 400 idempotency_key_reused.
• While the first request is still running, a second one with the same key gets 409 idempotency_key_in_use. Wait a moment and repeat with the same key.
• 4xx responses are stored and replayed too. 5xx responses are not: you may retry with the same key.

GET endpoints are idempotent by nature and ignore the header. On today's POST endpoints (checkout sessions, customers, portal sessions) the key is optional and recommended; on the charge endpoints that come next, it will be mandatory.

PaginationCopy Anchor Link

Every listing returns a list object:

{
  "object": "list",
  "url": "https://api.vipter.com/v1/orders",
  "has_more": true,
  "data": [
    { "id": "ord_7b3e9f1c2a8d4e6f", "object": "order", "created": 1790790412 },
    { "id": "ord_5c1e8a2b9d4f4e7a", "object": "order", "created": 1790704011 }
  ]
}

Items come newest first. Parameters, the same as Stripe's:

Do not send both cursors in the same call (400 parameter_invalid). A cursor that does not exist in the store gets 404 resource_missing, with param saying which. The endpoint's filters, such as customer or status, keep applying with the cursor.

To walk through everything, repeat while has_more is true, passing the last item's id in starting_after:

curl "https://api.vipter.com/v1/orders?limit=100" \
  -H "Authorization: Bearer vk_live_…"

# has_more: true, last id: ord_5c1e8a2b9d4f4e7a
curl "https://api.vipter.com/v1/orders?limit=100&starting_after=ord_5c1e8a2b9d4f4e7a" \
  -H "Authorization: Bearer vk_live_…"

Offers come in alphabetical order by name, not by date, because they are a small catalog. The cursors work the same way.

Rate limitsCopy Anchor Link

Each API key may make 100 requests every 2 seconds, which is 50 per second with room for bursts. Every response says where you stand:

Past the limit, the answer is 429 rate_limit with Retry-After in seconds. Wait that long and repeat. In an integration that sweeps a lot of data, use limit=100 and a small pause between pages instead of parallelizing calls.

Requests without a valid key have a separate limit, per IP address: 10 per minute.

Request-IdCopy Anchor Link

Every response, including errors and 429, carries a unique Request-Id:

Request-Id: req_8c2f4e6a1b3d5f7e9a0c

Record this value in your logs next to the call. When talking to Vipter support about a request, give the Request-Id: with it, support finds the exact call, with its status, duration and error. The same value appears in the dashboard's request logs, which are kept for 30 days.

Differences from StripeCopy Anchor Link

The API is not a clone: the goal is for a Stripe integration to be adapted by mapping, not for Stripe's SDK to work pointed at Vipter. What differs:

What to do nextCopy Anchor Link

• See every endpoint and every object in the API reference.
• Create and protect keys in Authentication and API keys.