Rebate Card X
StoresPartnersInvestorsHow it worksResources

Quickstart

Send your first Shopify order request with the required controls.

Follow the sequence from public API discovery to an authenticated order request, then see how later refunds and returns relate to it. Discovery needs no credential; order writes require reviewed access and an active tenant-scoped API key.

Prerequisites

Confirm access and prepare your server environment.

Use the environment provisioned for your integration and keep its credential server-side. If authentication modes are unfamiliar, review the authentication guide before following the write examples.

  • An approved Rebate Card X tenant and developer role.
  • An environment-specific API key with the orders:write scope.
  • A server runtime that can store secrets outside source code and client-visible configuration.
  • A unique, stable source identifier for every order, refund and return.
No account yet?

Read the documentation first, then request developer access with your company and integration context.

Step 1

Discover the live contract.

Requestcurl

curl --request GET \
  --url https://api.rebatecardx.com/api/v1 \
  --header "Accept: application/json"

A successful response is 200 and links to the environment health, dependency status, OpenAPI contract and human documentation. Use the openapi link instead of hardcoding a schema download path.

Step 2

Load the key from a secret store.

Authorization headerHTTP

Authorization: Bearer <RBX_API_KEY>

Keys begin with rbx_, are tied to one tenant and one environment, and are returned in full only when created. Store the value immediately; list operations expose only a prefix.

Step 3

Ingest a Shopify order with an idempotency key.

The example shows the order request format using integer USD cents and UTC timestamps. Replace its illustrative order details and placeholders with the appropriate values for your provisioned environment, following the request conventions.

POST /orderscurl

curl --request POST \
  --url https://api.rebatecardx.com/api/v1/orders \
  --header "Authorization: Bearer <RBX_API_KEY>" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-ord-10482-20260824" \
  --data '{
    "connector": "shopify",
    "integrationId": null,
    "externalId": "ord-10482",
    "status": "fulfilled",
    "totalAmount": 12900,
    "currency": "USD",
    "customerReference": "customer-7821",
    "orderedAt": "2026-08-24T09:15:00.000Z",
    "fulfilledAt": "2026-08-24T12:40:00.000Z",
    "lines": [
      {
        "externalId": "line-1",
        "sku": "RCX-CASE-01",
        "title": "Protective case",
        "quantity": 1,
        "unitAmount": 12900,
        "totalAmount": 12900
      }
    ]
  }'

201 responseapplication/json

{
  "data": {
    "id": "01J64M6H2Z8M6KQ2R1T8Q4Y7NP",
    "tenantId": "01J64M1H4EJ9B7K2D5P8S3V6XA",
    "connector": "shopify",
    "externalId": "ord-10482",
    "status": "fulfilled",
    "total": { "amount": 12900, "currency": "USD" },
    "fulfilledAt": "2026-08-24T12:40:00.000Z",
    "createdAt": "2026-08-24T12:41:03.000Z"
  }
}

Step 4

Retain the response and plan for an interrupted request.

  1. 01

    Reuse the key only for the same logical request

    A completed retry returns the stored response and the Idempotent-Replayed: true header.

  2. 02

    Stop on an idempotency conflict

    The same key with a different payload returns 409 IDEMPOTENCY_CONFLICT. Generate a new key only for a genuinely new operation.

  3. 03

    Retain the request ID

    Store X-Request-ID with the source operation so support can trace a failed request without receiving sensitive payloads.

  4. 04

    Record later adjustments

    Use the order identifier with POST /orders/{id}/refunds or POST /orders/{id}/returns; each adjustment requires its own idempotency key.

Order adjustments

Record refunds and returns against the platform order ID.

Both adjustment operations use the orders:write scope and a new idempotency key. The path identifier is the data.id returned by order ingestion, not your external order identifier.

Refund

POST /orders/{id}/refunds

Send a positive integer amount, your unique refund identifier, the UTC refund time and an optional reason.

Return

POST /orders/{id}/returns

Send your unique return identifier, source status, non-negative integer amount and optional UTC received time.

Record a refundcurl

curl --request POST \
  --url https://api.rebatecardx.com/api/v1/orders/<ORDER_ID>/refunds \
  --header "Authorization: Bearer <RBX_API_KEY>" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: refund-rf-8821-20260824" \
  --data '{
    "externalId": "rf-8821",
    "amount": 4900,
    "reason": "Item returned",
    "refundedAt": "2026-08-24T16:20:00.000Z"
  }'

Record a returncurl

curl --request POST \
  --url https://api.rebatecardx.com/api/v1/orders/<ORDER_ID>/returns \
  --header "Authorization: Bearer <RBX_API_KEY>" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: return-ret-3027-20260824" \
  --data '{
    "externalId": "ret-3027",
    "status": "received",
    "amount": 4900,
    "receivedAt": "2026-08-24T16:15:00.000Z"
  }'
Adjustments can change award state

The response includes awardPolicyOutcome. Treat award_held, issuance_cancelled, post_issuance_review and already_restricted as operational outcomes that must be retained with the adjustment.