Rebate Card X
StoresPartnersInvestorsHow it worksResources

Request mechanics

Format requests consistently and preserve operation identity.

Use these conventions with the schema for each API operation. They explain how to represent Shopify order information, interpret responses, retry mutations and avoid overwriting a newer resource version.

HTTP conventions

Match request headers to the operation and caller.

Some headers apply to server-to-server writes, while others belong to first-party session operations. Check the operation reference and authentication mode before combining them in a request.

HeaderWhen requiredPurpose
Accept: application/jsonRecommendedRequests the documented JSON representation.
Content-Type: application/jsonJSON request bodiesDeclares the exact body format.
AuthorizationAPI-key operationsCarries the tenant-scoped bearer credential.
Idempotency-KeyDocumented mutationsLinks safe retries of one logical operation.
If-MatchVersioned updatesPrevents a stale client from silently overwriting a newer state.
X-CSRF-TokenSession-authenticated mutationsBinds a first-party browser mutation to its authenticated session.

Data representation

Represent values in the format the schema expects.

Money
Amounts are integers in cents. 12900 means USD 129.00. The current platform currency is USD.
Timestamps
Send ISO 8601 UTC date-times such as 2026-08-24T12:40:00.000Z.
Identifiers
Treat platform IDs as opaque strings. Do not infer ordering, timestamps or business meaning from their shape.
Nullability
Send null only where the schema permits it. Omit optional values when no value is known.
Card data
PAN, CVV, PIN and track data are prohibited. Requests containing prohibited card data are rejected.

Envelopes

Read the result or the error before continuing.

A successful response and a failed request use different envelopes. Keep the result identifiers needed for later operations, and use the error guide when the response contains a failure.

Success

data contains the result

List responses may also include nextCursor. Versioned records can return an ETag header.

Failure

error contains the problem

Use code for program logic, message for diagnostics and requestId for support correlation.

List responseJSON

{
  "data": [
    { "id": "01J64M6H2Z8M6KQ2R1T8Q4Y7NP" }
  ],
  "nextCursor": "01J64M6H2Z8M6KQ2R1T8Q4Y7NP"
}

Idempotency

Retry one logical mutation with one stable key.

  • Use a key between 16 and 200 characters.
  • Keep the same key when retrying the exact same operation and JSON value.
  • Generate a different key for a new order, refund, return or other logical mutation.
  • A completed response is retained for 24 hours and replayed with Idempotent-Replayed: true.
  • A changed payload with an existing key returns 409 IDEMPOTENCY_CONFLICT.
  • A concurrent request using a key that is still processing returns 409 IDEMPOTENCY_IN_PROGRESS.

Optimistic concurrency

Update the version you actually read.

  1. 01

    Read the resource

    Retain the quoted ETag returned with the current version.

  2. 02

    Send If-Match

    Use the current ETag on the documented update or state transition.

  3. 03

    Resolve conflicts

    On 409 VERSION_CONFLICT, read the resource again and decide whether the intended change still applies.

Cursor pagination

Advance only with the returned cursor.

List operations that support pagination accept cursor and limit. The default limit is 50 and the maximum is 100. Omit the cursor on the first request, then pass nextCursor unchanged until it is null.

Next pageHTTP

GET /api/v1/orders?limit=50&cursor=<NEXT_CURSOR>