API integration flow

Your software shows a brand's products with price and stock and sends orders to the brand.

Before you start

• A test key from the brand, starting with "g4_test_". It works only on a sandbox brand with a demo catalogue.
• A server for your calls. The key never goes into browser or app code.

Check your key

Call "GET /v1/ping". The "customer" field tells you which kind of key you have:

API reference: "Authentication"

Import the catalogue

1. 1Call "GET /v1/collections".
2. 2Call "GET /v1/products" and follow "next_cursor" to the last page.
3. 3Call "GET /v1/products/{id}" for the description and composition.
4. 4Call "GET /v1/stock" and follow "next_cursor" to the last page.
5. 5Match stock to products by "variant_id".

API reference: "Conventions", "Collections and products", "Stock"

Receive webhooks

1. 1Send the brand your HTTPS address and the events you need. Agree a signing secret with it: a long random string you both keep.
2. 2Check "Go4-Signature" on the raw body, before you parse it.
3. 3Skip an event whose "Go4-Event-Id" you have already processed.
4. 4Answer 2xx within 10 seconds. Do slow work after you answer.

Events can arrive out of order. Compare "updated_at" before you apply one.

API reference: "Webhooks"

Keep the catalogue current

• "stock.updated" has the new quantities.
• "product.updated" has the ids of changed products. Fetch each product: "404" means it left your channel.
• Without webhooks, call products and stock with "updated_since".
• Run a full import at least once a day. Only a full import shows removed variants and new prices. Stop offering a variant whose "variant_id" is no longer returned.

API reference: "Catalogue visibility and removals"

Place an order

1. 1Call "POST /v1/orders" with a new "Idempotency-Key".
2. 2Put your order number in "external_ref".
3. 3Set "accept" to "all_or_nothing" to refuse the order on any shortage, or to "partial" to reject only the short lines.
4. 4After a timeout, send the same request with the same "Idempotency-Key".

Save the 201 response. Later reads of the order do not include rejected lines.

API reference: "Idempotency", "Place an order"

Follow the order

1. 1Apply changes from order, shipment and return events, or call "GET /v1/orders?updated_since=".
2. 2Call "GET /v1/orders/{id}" for shipments with tracking numbers and for invoices. Invoices have no event: read the order to find them.
3. 3Download an invoice PDF when you read the order. The link can expire after 5 minutes.
4. 4To cancel, call "POST /v1/orders/{id}/cancel". After a shipment, request a return instead.

API reference: "Order response and detail", "Cancel an order", "Returns"

Go live

1. 1Ask the brand for a "g4_live_" key.
2. 2Import the catalogue again from zero. Sandbox identifiers do not exist in the brand's data.
3. 3Ask the brand to add your webhook and click "Test connection". Your endpoint receives a webhook event of type "ping".
4. 4Place the first real order.

API reference: "Sandbox and go-live"

Check the result

Your first live order returns 201 with "status": "confirmed" and your number in "external_ref".

If it does not work

• An empty product list — the brand has no collection on sale in your channel yet. Ask the brand.
• "422 validation_failed" on "customer" — the order does not match your key. Send "customer" when the ping answer has "customer": null; leave it out when it is an object.
• "409 external_ref_conflict" — an order with this "external_ref" already exists. Read it by "details.order_id" instead of placing it again.
• "422 cannot_cancel" — the brand has started the order or issued a document for it. Contact the brand.
• "429" — wait for "Retry-After". "5xx" — retry with the same "Idempotency-Key". Other "4xx" — fix the request and send it with a new "Idempotency-Key".
• Anything else — send the brand the "X-Request-Id" of the response.