POST
/api/v1/orders/{id}/tagsAdd an internal order tag
Adds an internal tag owned by this app. Tags that already exist (including merchant or other app tags) are left unchanged and remain owned by their creator.
Required scope:
orders:write_tagsBearer tokenEnvironments
- SANDBOX
- Authorized local or test environment; no public hosted Sandbox is currently offered.
- PRODUCTION
https://getsas.xyz/api/v1/orders/{id}/tags
Request
Headers
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer <ACCESS_TOKEN> | Yes |
| Content-Type | application/json | Yes |
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id | path | string · uuid | Record UUID in the installation store. Other stores' records return 404. |
| Idempotency-Key | header | string | Unique per logical write for 24 hours. Retrying the same key with the same route, target and body returns the stored result without writing again; a different request with the same key returns 409 idempotency_conflict. |
Code examples
curl --request POST 'https://getsas.xyz/api/v1/orders/{id}/tags' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'
--header 'Idempotency-Key: <UNIQUE_KEY>'
--header 'Content-Type: application/json'
--data '{"tag":"vip"}'Response
200 Tag present on the order; created is false when the tag already existed
{
"description": "Tag present on the order; created is false when the tag already existed",
"headers": {
"RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderTagResponse"
}
}
}
}Errors
| 400 | Invalid request |
| 401 | Missing or invalid access token |
| 403 | The route, scope and reviewed contract do not match an operation this token can use (unsupported_capability) |
| 404 | The record does not exist in the installation store (records of other stores are indistinguishable), or the Marketplace API is unavailable |
| 409 | idempotency_conflict (the key was used for a different request), invalid_transition (for example the order is not confirmed or preparing) or conflict (duplicate code, SKU or slug) |
| 413 | The streamed write body exceeds 32,768 encoded bytes; it is rejected before JSON parsing |
| 415 | Write bodies must be sent as application/json (unsupported_media_type) |
| 422 | validation_failed or quota_exceeded; error.field names the rejected input when available |
| 429 | Fixed-window request limit exceeded for this installation and route key |
| 500 | Internal API failure |
| 503 | Rate-limit service unavailable; request is rejected closed |