# Order API Documentation ## 1. Documentation Scope & Source Confidence The supplied source material explicitly defines **2 of the 14 real endpoints** in this API: - `GET /v2/orders/{order_id}` — response fields `id`, `status` (`pending`/`fulfilled`/`refunded`), `total_amount` - `POST /v2/orders` — requires `customer_id` and a `line_items` array of `{sku, quantity}` objects The source states the remaining 12 endpoints "follow the same pattern," but does not name their paths, methods, parameters, or schemas. Nothing about those 12 endpoints is documented below — they are not inferable from a pattern description alone, and inventing plausible paths (e.g. `DELETE /v2/orders/{order_id}`, `GET /v2/orders`) would present guesses as fact. They are listed as a gap in Section 9. For the two documented endpoints: - Field **names** and, for `status`, the enum **values** are explicit in source. - Field **types** (string, number, integer) are not stated anywhere in the source and are inferred from naming/usage convention — flagged throughout. - The response body of `POST /v2/orders` is not described beyond "creates an order" — its shape is inferred, not explicit. - No error codes, rate limits, pagination, or idempotency behavior appear in the source; where included below, they are standard HTTP convention only, not API-specific fact. - Authentication (API key in `X-Api-Key`, issued per merchant via a developer portal) and versioning (URL path, current `/v2/`) are both explicit. Nothing in Sections 2–8 asserts more certainty than stated above. ## 2. API Overview & Authentication This API lets external e-commerce partners push and query orders programmatically on behalf of merchant clients they integrate for. The primary audience is third-party backend engineers building merchant-facing integrations *(explicit in source: API_PURPOSE_AND_AUDIENCE)*. **Base URL:** not present in the source material — only the version path segment `/v2/` is known. `<NEEDS-INPUT: base-url>` **Authentication procedure** *(explicit in source)*: 1. Each merchant obtains an API key through the developer portal, issued per merchant account. 2. Every request must include this key in the `X-Api-Key` request header: ```http X-Api-Key: {merchant_api_key} ``` 3. Behavior on a missing, invalid, or expired key is not specified in the source. By standard convention this would return `401 Unauthorized` (see Section 5), but the exact error body returned in this case is not defined. `<NEEDS-INPUT: auth-error-response-format>` ## 3. Endpoint Reference ### Orders **`GET /v2/orders/{order_id}`** — Retrieves a single order by ID. *(Explicit in source)* | Name | Type | Required | Description | |---|---|---|---| | `order_id` | string *(inferred from usage, not explicitly typed in source)* | Yes | Identifier of the order to retrieve | Success response: returns an `Order` object (defined in Section 4). --- **`POST /v2/orders`** — Creates a new order. *(Explicit in source)* Request body: | Name | Type | Required | Description | |---|---|---|---| | `customer_id` | string *(inferred from usage, not explicitly typed in source)* | Yes | Identifier of the customer the order belongs to | | `line_items` | array of `OrderLineItem` (see Section 4) | Yes | The items included in the order | Success response: the source states this endpoint "creates an order" but does not describe the response body. It is reasonable to expect an `Order` object is returned (standard REST convention), but this is not confirmed. `<NEEDS-INPUT: post-orders-response-schema>` --- ### Remaining endpoints The source confirms 12 additional endpoints exist and "follow the same pattern" as the two above, but supplies no paths, methods, parameters, or schemas for them. They are intentionally not listed here rather than invented. See Section 9. ## 4. Request & Response Schema Definitions **`Order`** *(fields explicit in source; types inferred from usage, not explicitly typed in source)* | Field | Type | Required | Description | |---|---|---|---| | `id` | string *(inferred)* | Yes | Unique order identifier | | `status` | string enum: `pending`, `fulfilled`, `refunded` *(values explicit in source; represented as a string type by inference)* | Yes | Current state of the order | | `total_amount` | number *(inferred)* | Yes | Total order value. Unit (minor currency unit vs. decimal) and currency are not specified in the source. `<NEEDS-INPUT: total-amount-unit-and-currency>` | **`OrderLineItem`** *(fields explicit in source; types inferred from usage, not explicitly typed in source)* | Field | Type | Required | Description | |---|---|---|---| | `sku` | string *(inferred)* | Yes | Identifier of the product/variant being ordered | | `quantity` | integer *(inferred)* | Yes | Number of units of the SKU in this order | ## 5. Error Code Reference No custom error codes or error-body structure appear anywhere in the source. Only standard HTTP convention is stated below; none of it is API-specific fact. | Status Code | Meaning *(standard convention)* | Common Trigger | Example Scenario | |---|---|---|---| | 400 | Bad Request | Missing or malformed required field | `POST /v2/orders` sent without `line_items` | | 401 | Unauthorized | Missing, invalid, or expired `X-Api-Key` | Request sent with no `X-Api-Key` header | | 404 | Not Found | Referenced resource does not exist | `GET /v2/orders/{order_id}` with an `order_id` that doesn't exist | | 429 | Too Many Requests | Rate limit exceeded | Exact threshold not defined in source, see Section 9 | | 500 | Internal Server Error | Unhandled server-side failure | Any endpoint, transient outage | The exact JSON error body shape returned for these codes is not defined in the source. `<NEEDS-INPUT: error-body-format>` ## 6. Versioning & Deprecation Policy Versioning scheme: URL path versioning, current version `/v2/` *(explicit in source)*. No endpoint, field, or prior version is marked as deprecated or sunset-dated anywhere in the source. The existence of a `/v1/` predecessor is implied by the `/v2/` label but is not confirmed or described, so no deprecation claim is made about it. `<NEEDS-INPUT: v1-deprecation-status>` ## 7. Usage Examples (Synthetic, Clearly Labeled) Example values are illustrative, not live data. **Retrieve an order** ```http GET /v2/orders/ord_9f2k4d X-Api-Key: {merchant_api_key} ``` ```json 200 OK { "id": "ord_9f2k4d", "status": "fulfilled", "total_amount": 4200 } ``` **Create an order** ```http POST /v2/orders X-Api-Key: {merchant_api_key} Content-Type: application/json { "customer_id": "cust_7a1b2c", "line_items": [ { "sku": "SKU-1001", "quantity": 2 }, { "sku": "SKU-2044", "quantity": 1 } ] } ``` ```json 201 Created { "id": "ord_a83jf2", "status": "pending", "total_amount": 8850 } ``` *(The response shape above assumes an `Order` object is returned, per the note in Section 3 — this is inferred, not confirmed by source.)* ## 8. Rate Limits & Operational Notes No rate limit thresholds, pagination conventions, or idempotency-key behavior appear in the source material. Rather than supply commonly-expected defaults, these are listed as data requests in Section 9. ## 9. Open Questions & Missing Source Material - `<NEEDS-INPUT: base-url>` — full base URL (host/domain) for the API is not given, only the `/v2/` path segment. - `<NEEDS-INPUT: auth-error-response-format>` — behavior and error body on invalid/expired `X-Api-Key` is not specified. - **Remaining 12 endpoints** — paths, methods, parameters, and schemas are not supplied; only their existence and "same pattern" claim are known. - `<NEEDS-INPUT: post-orders-response-schema>` — response body of `POST /v2/orders` is not described in source. - `<NEEDS-INPUT: total-amount-unit-and-currency>` — whether `total_amount` is a decimal or minor-unit integer, and what currency field (if any) accompanies it, is not stated. - `<NEEDS-INPUT: error-body-format>` — no custom error response structure is defined for any status code. - `<NEEDS-INPUT: v1-deprecation-status>` — whether a prior `/v1/` version exists and its deprecation status, if any. - `<NEEDS-INPUT: rate-limit-thresholds>` — request rate limits are not defined. - `<NEEDS-INPUT: pagination-convention>` — pagination behavior for any list-style endpoint (among the 12 undocumented ones) is unknown. - `<NEEDS-INPUT: idempotency-key-support>` — whether `POST /v2/orders` supports idempotency keys is not stated. **Inferred-type flags** (all field/parameter types below are inferred from naming convention, not explicitly typed in source): - `order_id` (path parameter) — inferred as string - `Order.id` — inferred as string - `Order.status` — value set explicit, type (string) inferred - `Order.total_amount` — inferred as number, unit unconfirmed - `customer_id` — inferred as string - `OrderLineItem.sku` — inferred as string - `OrderLineItem.quantity` — inferred as integer