Network calls can time out after PCE has already done the work. Onboarding makes creates safe to retry with the request-body externalId, which doubles as the idempotency key.

How it works

• Put a unique externalId on each POST.
• If a call times out and you resend the same request with that externalId, PCE returns the resource it already created instead of creating a duplicate.
• There is no separate Idempotency-Key header; the request-body externalId is the key.

externalId is your own reference, 1 to 255 characters (it can't be empty), and it's immutable once set. You can also use it to find a resource later; see Query Parameters.

Retry a create safely

Send a unique externalId on the create. If the response never arrives, resend the same request with the same externalId.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "acme-merchant-001", "legalName": "PCETest Acme Services LLC" }'

Response: 201 Created

{
  "id": "bus_40665d61-616d-4d7e-b6a6-5010dc9b31a4",
  "externalId": "acme-merchant-001",
  "legalName": "PCETest Acme Services LLC"
}

Resending that exact request returns the same bus_ id rather than creating a second business. Reusing the same externalId on a different payload is rejected with 409 Conflict (Duplicate externalId provided); see HTTP Response Codes.

🚧

PENDING-PUBLISH

That the request-body externalId is the sole idempotency key (with no header) is drawn from the boarding contract while the boarding spec is out of reference/. Confirm the idempotency behavior against the published API Reference before publish.

See also

• Query Parameters: resolve a resource by your externalId
• HTTP Response Codes: the 409 Conflict returned on a duplicate externalId
• Getting Started: creating and updating entities