go4.fashion API reference for developers

The go4.fashion API lets a partner's software (marketplace, partner shop, point of sale) read a brand's catalogue and stock, place orders and receive webhooks. One key identifies one brand and one sales channel.

Integration model

Base URL and versioning

Authentication

All endpoints require Bearer authentication, except "GET /v1/openapi.json":

GET /v1/ping HTTP/1.1
Host: api.go4.fashion
Authorization: Bearer g4_live_3f9a…   (64 hex characters after g4_live_)

"GET /v1/ping" confirms the key and returns what it grants:

{
  "ok": true,
  "organization_id": "…",
  "scopes": ["catalog:read", "stock:read", "orders:read", "orders:write"],
  "channel": { "id": "…", "code": "example_partner", "label": "Example Partner (API)" },
  "customer": { "id": "…", "name": "EXAMPLE PARTNER" },
  "environment": "live"
}

Scopes

A call without the required scope returns "403 insufficient_scope".

Conventions

Idempotency

Every "POST" request needs the "Idempotency-Key" header: 1–255 printable characters that identify one operation on your side. Use one key per operation and send it again on every retry of that operation, for example after a timeout. For 24 hours a key belongs to its first request and its answer, a 4xx such as 422 included. Send a corrected request with a new key, for example your order number with an attempt number: "MKT-2026-0001-2". Without the header the call returns "422 validation_failed" with field: "Idempotency-Key".

Request bodies are limited to 256 KB ("413 payload_too_large").

Errors

One envelope for every error:

{ "error": { "code": "insufficient_stock", "message": "Not enough stock for one or more lines.",
             "field": "items", "request_id": "8b1d…", "details": { "shortages": [ … ] } } }

What the "details" object carries:

Rate limits

Headers on every authenticated response: "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset" (ISO timestamp). On refusal: "Retry-After" (seconds).

Endpoints

The API has no endpoint for webhook subscriptions; see "Webhooks". Planned, not in v1 yet: "GET /v1/products/{id}/size-chart" with measurements per size.

Collections and products

Collection ("GET /v1/collections")

{ "id": "…", "name": "AW26", "season": "AW", "year": 2026, "sales_mode": "stock", "is_featured": true,
  "cutoff_at": null, "delivery_estimate": null, "products_count": 42, "cover_url": "https://…/cover.jpg",
  "updated_at": "…" }

Collections come in one response, featured collections first; do not rely on any other order. They do not support "updated_since": compare "updated_at" with your previous call to see which changed. The "sales_mode" field: "stock" — only units in stock; "quantity_available" limits your order. "preorder" — orders are accepted until "cutoff_at", without a stock limit. "stock_mto" — units in stock first, then made to order; the API does not show which units come from stock. The "delivery_estimate" field is a text the brand writes for the collection in your channel, for example "4–6 weeks"; null when not set.

"GET /v1/products" and "GET /v1/products/{id}" return the current unit price for every orderable variant in that channel. The price is agreed commercially between the brand and the partner outside the API.

Product ("GET /v1/products/{id}"; the list "GET /v1/products" has the same fields without "content" and "composition"; the OpenAPI specification has both schemas)

{ "id": "…", "name": "AURE hoodie", "product_number": "0022", "category": "hoodies",
  "product_type": "crop-hoodie", "collection": { "id": "…", "name": "AW26" }, "country_of_origin": "PL",
  "image_url": "https://…/main.jpg",
  "content": { "description_html": "…", "language": "en" },
  "composition": [ { "color_id": "…", "color_name": "Black", "composition": "100% organic cotton", "care": "Wash at 30°C, do not bleach" } ],
  "media": [ { "url": "https://…/….jpg", "type": "image", "video_url": null, "position": 1, "color_id": "…" } ],
  "colors": [ { "color_id": "…", "name": "Black", "hex": "#111111",
      "sizes": [ { "variant_id": "…", "size": "M", "sku": "0022-BLK-M", "ean": null, "weight_grams": 420,
                   "price": { "amount": 38, "currency": "EUR", "price_list": "Example Partner" },
                   "retail_price": { "amount": 109, "currency": "EUR" } } ] } ],
  "updated_at": "…" }

Stock

Stock item ("GET /v1/stock")

{ "variant_id": "…", "product_id": "…", "quantity_available": 3, "updated_at": "…" }

Map "variant_id" to the variant you synced from "/v1/products". The "quantity_available" field is a snapshot of what your channel can order now, and it can be lower than the brand's total stock. It reserves nothing: go4.fashion checks stock again when it creates the order, so an order can be rejected or partly accepted even after a stock call showed enough.

Catalogue visibility and removals

• "GET /v1/products" returns only products on sale in your channel, also in incremental calls.
• A product leaves your channel when the brand ends the collection's offer, hides the product in your channel or archives it. It is then no longer returned, "GET /v1/products/{id}" returns "404 not_found", and no webhook is sent.
• A variant the brand archives disappears from "sizes" and from "/v1/stock".
• An incremental sync cannot detect a removal. Run a full sync at least once a day and compare variants by "variant_id": when a product, or a variant in a product's "sizes", is missing, deactivate your offer for it and keep your order history.
• A variant with "price": null cannot be ordered. A variant with "quantity_available": 0 is out of stock and can come back.

Place an order

"POST /v1/orders", with the header "Idempotency-Key" (see "Idempotency"):

{ "external_ref": "MKT-2026-0001", "currency": "EUR", "accept": "partial",
  "shipping_address": { "name": "Example Partner GmbH", "contact": "Lena", "email": "ops@partner.example", "phone": "+49…",
                        "line1": "Hafenstr. 1", "line2": null, "city": "Hamburg", "state": null, "zip": "20457", "country": "DE" },
  "items": [ { "variant_id": "…", "quantity": 2, "unit_price": 38 } ] }

The order uses the current price of each variant in your channel. A "unit_price" you send does not change it: when it differs by more than 0.01, the order has "price_adjusted": true.

Order response and detail

Order (201 from "POST /v1/orders", entries of "data" in "GET /v1/orders")

{ "id": "…", "number": "1234_EXP", "status": "confirmed", "external_ref": "MKT-2026-0001",
  "channel": { "id": "…", "code": "example_partner", "label": "Example Partner (API)" },
  "customer": { "id": "…", "name": "EXAMPLE PARTNER" },
  "currency": "EUR", "exchange_rate": null,
  "totals": { "subtotal": 76, "discount": 0, "total": 76 }, "price_adjusted": false,
  "items": [ { "variant_id": "…", "product_id": "…", "sku": "0022-BLK-M", "product_name": "AURE hoodie", "color": "Black", "size": "M",
               "quantity": 2, "unit_price": 38, "original_price": null, "line_total": 76,
               "status": "accepted", "reason": null, "available": null },
             { "variant_id": "…", "product_id": "…", "sku": "0022-BLK-L", "product_name": "AURE hoodie", "color": "Black", "size": "L",
               "quantity": 3, "unit_price": 38, "original_price": null, "line_total": 0,
               "status": "rejected", "reason": "insufficient_stock", "available": 1 } ],
  "shipping_address": { "name": "…", "contact": null, "email": null, "phone": null, "line1": "…", "line2": null, "city": "…", "state": null, "zip": "…", "country": "DE" },
  "fulfillment_status": "unfulfilled", "payment_status": "unpaid",
  "created_at": "…", "confirmed_at": "…", "updated_at": "…" }

Store the response of "POST /v1/orders": rejected lines are not returned by later reads of the order.

The "totals" object is the sum of the accepted order lines. Shipping and other charges the brand adds later are not in "totals". The API does not calculate tax; whether a price includes VAT follows your agreement with the brand. The brand's invoice in "documents" shows tax and the amount to pay, which can differ from "totals".

Order detail ("GET /v1/orders/{id}", also returned by "POST /v1/orders/{id}/cancel") adds:

{ "shipments": [ { "id": "…", "number": 1, "status": "shipped", "packed_at": "…", "shipped_at": "…", "delivered_at": null,
                   "carrier": "ups", "carrier_service": "UPS Standard", "tracking_number": "1Z…", "tracking_url": "https://www.ups.com/track?tracknum=1Z…",
                   "ship_to": { … }, "items": [ { "variant_id": "…", "sku": "0022-BLK-M", "quantity": 1 } ],
                   "cartons": [ { "number": 1, "tracking_number": "1Z…", "weight_grams": 600, "length_cm": 40, "width_cm": 30, "height_cm": 20,
                                  "items": [ { "variant_id": "…", "sku": "0022-BLK-M", "quantity": 1 } ] } ] } ],
  "awaiting": [ { "variant_id": "…", "sku": "0022-BLK-M", "quantity": 1 } ],
  "documents": [ { "id": "…", "kind": "final", "number": "11/S/EX/09/2026", "status": "issued", "amount": 76, "currency": "EUR",
                   "issued_at": "…", "paid_at": null, "pdf_url": "https://…" } ] }

Shipment "status": "packed" → "shipped" → "delivered". The "awaiting" list has the units not shipped yet; units in a packed carton still count as awaiting. The "documents" list has the brand's billing documents; drafts and cancelled documents are left out. The "pdf_url" field is a link to the PDF, or null when there is no file yet. Some links expire after 5 minutes: download the file when you read the order, or read the order again for a new link.

Cancel an order

"POST /v1/orders/{id}/cancel" cancels the order. It needs an "Idempotency-Key"; the body is optional: { "reason": "…" }. Cancelling an already cancelled order returns it unchanged. When the order can no longer be cancelled, the call returns "422 cannot_cancel", and "details.reason" says why:

To stop the order after that, contact the brand; after a shipment, request a return.

Returns

Return request ("POST /v1/orders/{id}/returns", "Idempotency-Key" required)

{ "resolution": "refund", "note": "Wrong size",
  "items": [ { "variant_id": "…", "quantity": 1, "reason": "size", "condition": "unworn", "note": null, "external_line_id": "L-1" } ] }

The "resolution" field: "refund", "credit", "exchange" or "none" — what the customer asks for. With "exchange", the replacement is arranged with the brand outside the API. The "reason" field: "size", "fit", "quality", "wrong_item", "damaged_in_transit", "changed_mind" or "other". The "condition" field: "unworn", "worn", "damaged" or "defective". Only shipped units can be returned; a quantity above what is left is rejected with "422 validation_failed" on that line, with "available" in "details".

Return (201 from the request, entries of "data" in "GET /v1/orders/{id}/returns")

{ "id": "…", "order_id": "…", "number": 1, "reference": "1234_EXP/R1", "kind": "return", "resolution": "refund", "status": "requested",
  "requested_at": "…", "approved_at": null, "declined_at": null, "cancelled_at": null, "closed_at": null,
  "ship_back_by": null, "customer_shipped_at": null, "parcel_received_at": null, "return_carrier": null, "return_tracking_number": null,
  "currency": "EUR", "goods_amount": 38, "refund_amount": 38, "qty_requested": 1, "qty_received": 0,
  "items": [ { "variant_id": "…", "sku": "0022-BLK-M", "quantity": 1, "reason": "size", "condition": "unworn", "unit_price": 38, "line_amount": 38, "external_line_id": "L-1" } ] }

Return "status": "requested" → "approved" (by the brand) → "in_transit" (parcel on its way) → "partly_received" or "received" → "closed"; or "declined" or "cancelled". The brand sets "ship_back_by" when approving.

Webhooks

Send the brand your endpoint, an HTTPS address on a public host, and the events you want. You and the brand share a signing secret: a long random string that both sides keep. The brand adds both in go4.fashion under "Settings" → "Integrations" → "Add integration" → "Webhook". You receive events only for your sales channel. To test your endpoint, ask the brand to click "Test connection": it sends a "ping" event. Each delivery is a POST:

Body: { "id", "type", "created_at", "api_version": "v1", "data": { … } }.

Answer with a 2xx status within 10 s. A timeout, a network error, a 5xx, 401 or 429 is retried after 1 min, 5 min, 30 min, 2 h and 12 h. Any other 4xx stops the delivery at once. A stopped delivery, and one that fails its last retry, is not sent again automatically; ask the brand to retry it in go4.fashion.

Webhooks are delivered at least once: the same event can arrive more than once, and events can arrive out of order. Deduplicate on "Go4-Event-Id". Do not take the current state from the order in which events arrive: compare "updated_at", or read the resource from the API. For a product event, "404 not_found" from "GET /v1/products/{id}" means the product left your channel; deactivate your offer. Webhooks shorten the delay; keep the daily full sync.

To change the signing secret, first make your endpoint accept both the current and the new secret. Then give the new secret to the brand, which saves it in go4.fashion. Keep accepting both during the agreed transition, then remove the old one.

Verifying the signature (Node.js):

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyGo4Signature(rawBody, header, secret) {
  const t = /(?:^|,)\s*t=(\d+)(?:,|$)/.exec(header)?.[1];
  const v1 = /(?:^|,)\s*v1=([0-9a-f]{64})(?:,|$)/.exec(header)?.[1];
  if (!t || !v1) return false;
  const timestamp = Number(t);
  if (!Number.isSafeInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const received = Buffer.from(v1, "hex");
  return received.length === expected.length && timingSafeEqual(expected, received);
}

Verify the signature on the raw body exactly as received, before you parse the JSON — re-serialised JSON produces a different signature. Reject a delivery with an invalid signature before you queue it. Record "Go4-Event-Id" in the same transaction as your change, so a retry does not apply it twice.

Sandbox and go-live

1. 1Ask the brand for a "g4_test_" key. It works on a sandbox brand with a demo catalogue and stock.
2. 2Call "ping" and check "customer" in the answer: when it is an object, leave "customer" out of your orders.
3. 3Test the whole flow: sync catalogue and stock → place a test order → cancel it → receive a webhook. For the webhook, send the brand your endpoint and ask it to switch on "order.confirmed" and "order.cancelled" for the sandbox.
4. 4Ask the brand for the "g4_live_" key. Keep it on your server; ask the brand to rotate it when a person who saw it leaves your team. Run a full sync with the live key: identifiers from the sandbox do not exist in the brand's live data.

Changelog