Authentication

Every request to the Merchant Data API must be authenticated with HTTP Basic
authentication. There is no OAuth flow, no bearer token, and no login step: you send
your credentials on every request.

Your credentials

Your Shop ID (the numeric shop identifier used as your API username) is resolved to a
merchant account on every request, and all query results are automatically scoped to
that merchant. You cannot query another merchant's data.

Sending credentials

HTTP Basic authentication sends your credentials in the Authorization header as a
Base64-encoded username:password pair. Most HTTP clients build this header for you.

cURL

curl -X POST https://api.payretailers.com/data-api/graphql \
  -u "YOUR_SHOP_ID:YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { currentMerchantId }"}'

Raw header

If you build the header yourself, Base64-encode YOUR_SHOP_ID:YOUR_API_TOKEN:

POST /data-api/graphql HTTP/1.1
Host: api.payretailers.com
Authorization: Basic <base64(YOUR_SHOP_ID:YOUR_API_TOKEN)>
Content-Type: application/json

{"query": "query { currentMerchantId }"}

Response

{
  "data": {
    "currentMerchantId": "48213"
  }
}

The currentMerchantId query is a convenient way to confirm which merchant account your
credentials resolve to.

Language examples

TypeScript (fetch)

const shopId = process.env.SHOP_ID!;
const apiToken = process.env.API_TOKEN!;
const auth = Buffer.from(`${shopId}:${apiToken}`).toString("base64");

const res = await fetch("https://api.payretailers.com/data-api/graphql", {
  method: "POST",
  headers: {
    "Authorization": `Basic ${auth}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "query { currentMerchantId }" }),
});

const body = await res.json();
if (body.errors) {
  throw new Error(`API error: ${body.errors[0].extensions?.code}`);
}
console.log(body.data.currentMerchantId);

Python (requests)

import os
import requests

resp = requests.post(
    "https://api.payretailers.com/data-api/graphql",
    auth=(os.environ["SHOP_ID"], os.environ["API_TOKEN"]),
    headers={"Content-Type": "application/json"},
    json={"query": "query { currentMerchantId }"},
    timeout=30,
)
body = resp.json()
if "errors" in body:
    raise RuntimeError(f"API error: {body['errors'][0]['extensions']['code']}")
print(body["data"]["currentMerchantId"])

When authentication fails

If credentials are missing or invalid, the API returns UNAUTHORIZED, also delivered as
HTTP 401:

{
  "errors": [
    {
      "message": "Your credentials are missing or could not be validated.",
      "extensions": {
        "code": "UNAUTHORIZED",
        "retryable": false
      }
    }
  ]
}

If your credentials are valid but your merchant account cannot be resolved, you receive
MERCHANT_ID_MISSING. See Error handling for the full list.

Security guidance

• Treat your API token like a password. Never embed it in client-side code, mobile
  apps, or public repositories.
• Store credentials in a secrets manager or environment variables, not in source.
• Always call the API over HTTPS; never send credentials over plain HTTP.
• If you believe your token is compromised, contact PayRetailers to have it rotated.

_review_needed: The source material does not define an expiry or rotation policy
for the API token. Confirm token lifetime and rotation procedure with the team before
publication.