{ "openapi": "3.1.1", "info": { "title": "MerchJar Public API", "version": "v5", "description": "The contract for the customer-facing MerchJar Public API. All paths in this document are relative to the server URL.\n\n## Getting started\n\n### Base URL\n\nAll requests use `https://app.merchjar.com/api/v5`.\n\n### Authentication\n\nSend a provisioned MerchJar API key with every request:\n\n```sh\ncurl https://app.merchjar.com/api/v5/profiles \\\n -H 'Authorization: Bearer mj_live_…'\n```\n\n[Create and manage API keys in Settings > API Keys](https://app.merchjar.com/api-keys). The full key is shown only once when you create it. Start with [GET /profiles](#tag/Profiles/operation/listProfiles) to discover the profile IDs available to the key.\n\n### Scopes\n\nAPI keys are limited by scopes. Every operation lists its required scope in `x-merchjar-required-scope`; a key without that scope receives `403 Forbidden`.\n\n- `profiles:read`: List accessible Amazon Advertising profiles.\n- `segments:read`: List and retrieve segments and their schedules.\n- `segments:write`: Create, update, and delete segments and schedules.\n- `segments:preview`: Preview segment results.\n- `segments:validate`: Validate a segment definition.\n- `audit_logs:read`: List audit logs and audit-log items.\n- `history:read`: Retrieve entity change history.\n- `targets:read`: Read Sponsored Products targets.\n- `campaigns:write`: Create and update Sponsored Products campaigns.\n- `campaigns:archive`: Archive Sponsored Products campaigns.\n- `ad_groups:write`: Create and update Sponsored Products ad groups.\n- `ad_groups:archive`: Archive Sponsored Products ad groups.\n- `ads:write`: Create and update Sponsored Products product ads.\n- `ads:archive`: Archive Sponsored Products product ads.\n- `targets:write`: Create and update Sponsored Products targets.\n- `targets:archive`: Archive Sponsored Products targets.\n- `negative-targets:write`: Create Sponsored Products negative product targets.\n- `negative-targets:archive`: Archive Sponsored Products negative targets.\n- `bulk_actions:read`: Retrieve submitted bulk actions.\n- `custom_fields:read`: Read custom-field catalogs, values, and CSV exports.\n- `custom_fields:write`: Manage custom-field definitions, values, and CSV imports.\n\n### Rate limits and retries\n\nUse the response headers to make retry decisions; limits are enforced before the operation runs.\n\n| Request type | Limit | Identity | On exhaustion |\n| --- | --- | --- | --- |\n| Standard API operations | 1,200 requests per minute by default; an API key may have a configured override | API key | `429` with `Retry-After`; standard rate limit headers appear on successful and rate limited responses |\n| `POST /segments/preview` | In addition to the standard limit: a 3-request burst that refills one request every 2 seconds by default | Account, shared across its API keys | `429` with `Retry-After`; the rate limit headers report the preview-admission bucket |\n| Campaign, ad-group, product-ad, and target creation | No standard rate limit middleware currently | Not applicable | These endpoints do not emit the standard rate limit headers or standard `429`/`503` rate limit responses |\n\nRetry a `429` after the supplied `Retry-After` value. Retry a `503` only when that response includes `Retry-After`; otherwise investigate before retrying.\n\n### Compatibility\n\nMerchJar makes additive, backward-compatible changes within v5. A breaking change uses a new API version and is documented in the reference before release. Deprecated operations remain documented with migration guidance and a removal date.\n\n### Errors\n\nHandled API errors use a JSON envelope with `error.code` and `error.message`. Use the HTTP status to choose the next action: correct `400` requests, replace invalid or revoked `401` keys, request the required scope after `403`, retry `429` after `Retry-After`, and retry only `503` responses that include `Retry-After`.\n\n### Segment frequencies and clock schedules\n\nSegments return one of six frequencies. Five are writable; `scheduled` is server-managed.\n\n| Returned value | Writable | Contract |\n| --- | --- | --- |\n| `after_every_data_sync` | Yes | Runs after each data sync. |\n| `daily` | Yes | Runs daily. |\n| `weekly` | Yes | Runs weekly. |\n| `monthly` | Yes | Runs monthly. |\n| `manual` | Yes | Never runs automatically and never has a schedule. |\n| `scheduled` | No | Set by `PUT /segments/{id}/schedule`. Create rejects it with `schedule_required`; PATCH rejects it unless a schedule exists, when it is a no-op. |\n\nPATCH from `scheduled` to another frequency removes the schedule and skips future runs. `DELETE /segments/{id}/schedule` switches the segment to `manual`.\n" }, "servers": [ { "url": "https://app.merchjar.com/api/v5", "description": "Production" } ], "security": [ { "API-Key": [] } ], "tags": [ { "name": "Profiles", "description": "List profiles available to your API key." }, { "name": "Segments", "description": "Validate, preview, and manage segments." }, { "name": "Audit logs", "description": "Review audit logs and entity changes." }, { "name": "History", "description": "View bid and budget changes." }, { "name": "Custom fields", "description": "Manage field definitions, values, and CSV jobs." }, { "name": "Targets", "description": "List and retrieve Sponsored Products targets." }, { "name": "Campaign creation", "description": "Create Sponsored Products campaigns." }, { "name": "Ad group creation", "description": "Create Sponsored Products ad groups." }, { "name": "Product ad creation", "description": "Create Sponsored Products ads." }, { "name": "Target creation", "description": "Create Sponsored Products targets." }, { "name": "Bulk actions", "description": "Manage bulk actions." } ], "x-merchjar-scopes": [ { "id": "profiles:read", "label": "Profiles: Read", "description": "List accessible Amazon Advertising profiles.", "group": "Profiles" }, { "id": "segments:read", "label": "Segments: Read", "description": "List and retrieve segments and their schedules.", "group": "Segments" }, { "id": "segments:write", "label": "Segments: Write", "description": "Create, update, and delete segments and schedules.", "group": "Segments" }, { "id": "segments:preview", "label": "Segments: Preview", "description": "Preview segment results.", "group": "Segments" }, { "id": "segments:validate", "label": "Segments: Validate", "description": "Validate a segment definition.", "group": "Segments" }, { "id": "audit_logs:read", "label": "Audit Logs: Read", "description": "List audit logs and audit-log items.", "group": "Audit logs" }, { "id": "history:read", "label": "Bid History: Read", "description": "Retrieve entity change history.", "group": "History" }, { "id": "targets:read", "label": "Targets: Read", "description": "Read Sponsored Products targets.", "group": "Sponsored Products reads" }, { "id": "campaigns:write", "label": "Campaigns: Write", "description": "Create and update Sponsored Products campaigns.", "group": "Sponsored Products mutations" }, { "id": "campaigns:archive", "label": "Campaigns: Archive", "description": "Archive Sponsored Products campaigns.", "group": "Sponsored Products mutations" }, { "id": "ad_groups:write", "label": "Ad groups: Write", "description": "Create and update Sponsored Products ad groups.", "group": "Sponsored Products mutations" }, { "id": "ad_groups:archive", "label": "Ad groups: Archive", "description": "Archive Sponsored Products ad groups.", "group": "Sponsored Products mutations" }, { "id": "ads:write", "label": "Product ads: Write", "description": "Create and update Sponsored Products product ads.", "group": "Sponsored Products mutations" }, { "id": "ads:archive", "label": "Product ads: Archive", "description": "Archive Sponsored Products product ads.", "group": "Sponsored Products mutations" }, { "id": "targets:write", "label": "Targets: Write", "description": "Create and update Sponsored Products targets.", "group": "Sponsored Products mutations" }, { "id": "targets:archive", "label": "Targets: Archive", "description": "Archive Sponsored Products targets.", "group": "Sponsored Products mutations" }, { "id": "negative-targets:write", "label": "Negative targets: Write", "description": "Create Sponsored Products negative product targets.", "group": "Sponsored Products mutations" }, { "id": "negative-targets:archive", "label": "Negative targets: Archive", "description": "Archive Sponsored Products negative targets.", "group": "Sponsored Products mutations" }, { "id": "bulk_actions:read", "label": "Bulk actions: Read", "description": "Retrieve submitted bulk actions.", "group": "Bulk actions" }, { "id": "custom_fields:read", "label": "Custom fields: Read", "description": "Read custom-field catalogs, values, and CSV exports.", "group": "Custom fields" }, { "id": "custom_fields:write", "label": "Custom fields: Write", "description": "Manage custom-field definitions, values, and CSV imports.", "group": "Custom fields" } ], "x-merchjar-retired-scopes": [], "x-merchjar-bigint-convention": "Every Amazon and MerchJar identifier that can exceed JavaScript's safe-integer range is a base-10 string. Clients must not send or parse these values as JSON numbers.", "paths": { "/ad-groups": { "post": { "operationId": "createSponsoredProductsAdGroups", "tags": [ "Ad group creation" ], "summary": "Create ad groups", "description": "Creates between 1 and 1,000 Sponsored Products ad groups for the API-key-authorized `profileid` header. The request schema is strict: `profile_id` and every other undeclared field are rejected before MerchJar calls Amazon. `campaignId` is forwarded directly to Amazon; MerchJar does not locally check that the campaign exists or is compatible. The 200 response is Amazon's raw batch envelope, without a MerchJar wrapper. A `success` or `partialSuccess` result queues local projection; browse data is eventually consistent and the response does not report projection completion. An error-only Amazon envelope is also passed through, but does not queue a receipt. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This router does not currently install the API-key rate limit middleware, so it does not emit the standard rate limit headers or 429/503 rate limit responses.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "ad_groups:write", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Positive PostgreSQL signed-bigint Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.", "schema": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6][0-9]{0}|9223372036854775807)$", "example": "9007199254740993" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adGroups" ], "properties": { "adGroups": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "required": [ "adProduct", "campaignId", "name", "state", "bid" ], "properties": { "adProduct": { "const": "SPONSORED_PRODUCTS" }, "campaignId": { "type": "string", "description": "Positive PostgreSQL signed-bigint Amazon campaign ID encoded as a decimal string, never a JavaScript number.", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6][0-9]{0}|9223372036854775807)$", "example": "9007199254740995" }, "name": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ] }, "bid": { "type": "object", "required": [ "defaultBid", "currencyCode" ], "properties": { "defaultBid": { "type": "number", "exclusiveMinimum": 0 }, "currencyCode": { "type": "string", "enum": [ "AED", "AUD", "BRL", "CAD", "EGP", "EUR", "GBP", "INR", "JPY", "MXN", "PLN", "SAR", "SEK", "SGD", "TRY", "USD" ] } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Amazon's raw batch-create envelope. At least one non-empty `success`, `partialSuccess`, or `error` array is present. Fields inside each Amazon result item are passed through unchanged and may evolve with Amazon's API.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": {} }, "partialSuccess": { "type": "array", "items": {} }, "error": { "type": "array", "items": {} } }, "anyOf": [ { "required": [ "success" ], "properties": { "success": { "minItems": 1 } } }, { "required": [ "partialSuccess" ], "properties": { "partialSuccess": { "minItems": 1 } } }, { "required": [ "error" ], "properties": { "error": { "minItems": 1 } } } ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON or strict create schema (`invalid_request`), an invalid `profileid` (`invalid_profile_id`), or a request that reaches the handler without trusted profile context (`missing_profile_context`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "invalid_profile_id", "missing_profile_context" ] }, "message": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Amazon transport failed or returned an envelope with no non-empty `success`, `partialSuccess`, or `error` array. The ad-group create may have reached Amazon; MerchJar does not retry it. Check Amazon before retrying.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "public_create_outcome_unknown" }, "message": { "const": "Ad group creation outcome is unknown; check Amazon before retrying" } }, "additionalProperties": false } }, "additionalProperties": false } } } } } } }, "/ad-groups/{id}": { "patch": { "operationId": "updateSponsoredProductsAdGroup", "tags": [ "Ad group creation" ], "summary": "Update an ad group", "description": "Updates only `defaultBid` and/or `state` for one Sponsored Products ad group. An `Idempotency-Key` is required; unknown outcomes must be checked before retrying.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "ad_groups:write", "parameters": [ { "name": "id", "in": "path", "required": true, "example": "9007199254740995", "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "profileid", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bid": { "type": "object", "required": [ "defaultBid" ], "properties": { "defaultBid": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "state": { "enum": [ "ENABLED", "PAUSED" ] } }, "anyOf": [ { "required": [ "bid" ] }, { "required": [ "state" ] } ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Amazon raw update envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Ad group not found" }, "502": { "description": "Outcome unknown; verify Amazon before retrying" } } }, "delete": { "operationId": "archiveSponsoredProductsAdGroup", "tags": [ "Ad group creation" ], "summary": "Delete an ad group", "description": "Archives one Sponsored Products ad group and confirms Amazon reports `ARCHIVED` before local projection. An Idempotency-Key is required.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "ad_groups:archive", "parameters": [ { "name": "id", "in": "path", "required": true, "example": "9007199254740995", "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "profileid", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Amazon raw delete envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Ad group not found" }, "409": { "description": "Ad group is already archived" }, "502": { "description": "Outcome unknown; verify Amazon before retrying" } } } }, "/audit-logs": { "get": { "operationId": "listAuditLogs", "tags": [ "Audit logs" ], "summary": "List audit logs", "description": "Lists profile-scoped records of MerchJar changes. The default date window is the 30 calendar days ending today, calculated when the request is handled.", "x-merchjar-required-scope": "audit_logs:read", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Positive decimal Amazon Advertising profile ID owned by the API-key user.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "maxLength": 19, "example": "9007199254740993" } }, { "name": "page", "in": "query", "required": false, "description": "One-based page number. Missing, non-positive, or non-numeric values fall back to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page. Missing, non-positive, or non-numeric values fall back to 25; values above 100 are capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive UTC start date. Send an ISO calendar date such as `2026-03-01`; the route uses the start of that day. Defaults to 30 days ago.", "schema": { "type": "string", "example": "2026-03-01" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive UTC end date. Send an ISO calendar date such as `2026-03-31`; the route uses the end of that day. Defaults to today.", "schema": { "type": "string", "example": "2026-03-31" } }, { "name": "target_type", "in": "query", "required": false, "description": "Filter by affected entity type.", "schema": { "type": "string", "enum": [ "campaigns", "ad_groups", "product_ads", "keywords", "targets", "campaign_negative_keywords", "negative_keywords", "negative_targets", "portfolios", "promotions", "recipes", "search_terms", "ads", "placements" ] } }, { "name": "source_type", "in": "query", "required": false, "description": "Filter by the type of source that initiated the audit log.", "schema": { "type": "string", "enum": [ "smart_bids", "promotion", "recipe", "bulk_action", "public_api" ] } }, { "name": "source_id", "in": "query", "required": false, "description": "Filter by source ID. Send the ID as a decimal string so clients do not lose bigint precision.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "example": "9007199254740995" } }, { "name": "count", "in": "query", "required": false, "description": "Filter on `meta.count`: `gt:N`, `gte:N`, `lt:N`, `lte:N`, `eq:N`, `neq:N`, or `between:N,M`.", "schema": { "type": "string", "pattern": "^(?:gt|gte|lt|lte|eq|neq):-?[0-9]+$|^between:-?[0-9]+,-?[0-9]+$", "example": "gt:10" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort by `created_at` (the default) or `effected_entities`; prefix either with `-` for descending order. Unknown sort fields currently fall back to `created_at`.", "schema": { "type": "string", "default": "-created_at" } } ], "responses": { "200": { "description": "Paginated audit logs matching the profile and supplied filters.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "profile_id", "target_type", "source_type", "source_id", "meta", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Audit-log ID serialized as a decimal string." }, "profile_id": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Profile ID serialized as a decimal string." }, "target_type": { "type": "string", "description": "Mapped target type; unrecognized stored numeric values serialize as `unknown`." }, "source_type": { "type": "string", "enum": [ "smart_bids", "promotion", "recipe", "bulk_action", "public_api", "unknown" ], "description": "Mapped source type; unrecognized stored numeric values serialize as `unknown`." }, "source_id": { "type": [ "string", "null" ], "description": "Source ID serialized as a decimal string, when present." }, "meta": { "description": "Source-specific audit metadata.", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "description": "Audit-log creation timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "Audit-log update timestamp." } }, "additionalProperties": false } }, "pagination": { "type": "object", "required": [ "page", "per_page", "total", "last_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "last_page": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "The audit-log query failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "internal_error" }, "message": { "const": "Failed to list audit logs" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/audit-logs/{id}/items": { "get": { "operationId": "listAuditLogItems", "tags": [ "Audit logs" ], "summary": "List audit log changes", "description": "Returns items only after verifying that the parent audit log belongs to the requested profile. The item data is retrieved from MerchJar's internal Laravel service and bigint identifiers are re-serialized as strings.", "x-merchjar-required-scope": "audit_logs:read", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Positive decimal Amazon Advertising profile ID owned by the API-key user.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "maxLength": 19, "example": "9007199254740993" } }, { "name": "id", "in": "path", "required": true, "description": "Audit-log ID as a decimal string.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "example": "789" } }, { "name": "page", "in": "query", "required": false, "description": "One-based page number. Missing, non-positive, or non-numeric values fall back to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page. Missing, non-positive, or non-numeric values fall back to 25; values above 100 are capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "target_type", "in": "query", "required": false, "description": "Filter item rows by target entity type.", "schema": { "type": "string", "enum": [ "campaigns", "ad_groups", "product_ads", "keywords", "targets", "campaign_negative_keywords", "negative_keywords", "negative_targets", "portfolios", "promotions", "recipes", "search_terms", "ads", "placements" ] } }, { "name": "target_id", "in": "query", "required": false, "description": "Filter item rows by affected entity ID. Send the ID as a decimal string so clients do not lose bigint precision.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "example": "9007199254740997" } } ], "responses": { "200": { "description": "Paginated audit-log items and the parent audit-log summary.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "audit_log" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "audit_log_id", "target_id", "target_type", "meta", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "audit_log_id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "target_id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "target_type": { "type": "string", "description": "Mapped target type; unrecognized stored numeric values serialize as `unknown`." }, "meta": { "description": "Item-specific change metadata.", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "pagination": { "type": "object", "required": [ "page", "per_page", "total", "last_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "last_page": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "audit_log": { "type": "object", "required": [ "id", "profile_id", "target_type", "source_type", "source_id", "meta", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "profile_id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "target_type": { "type": "string", "description": "Mapped target type; unrecognized stored numeric values serialize as `unknown`." }, "source_type": { "type": "string", "enum": [ "smart_bids", "promotion", "recipe", "bulk_action", "public_api", "unknown" ], "description": "Mapped source type; unrecognized stored numeric values serialize as `unknown`." }, "source_id": { "type": [ "string", "null" ] }, "meta": { "description": "Source-specific audit metadata.", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No audit log with this ID belongs to the requested profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "not_found" }, "message": { "const": "Audit log not found" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "The audit-log ownership lookup or response serialization failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "internal_error" }, "message": { "const": "Failed to fetch audit log items" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "502": { "description": "MerchJar's internal audit-log-items service did not return a successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "upstream_error" }, "message": { "const": "Failed to fetch audit log items" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/bulk-actions": { "post": { "operationId": "submitBulkAction", "tags": [ "Bulk actions" ], "summary": "Create bulk action", "description": "Submits a profile-scoped bulk action for asynchronous processing. Submit, then poll `GET /bulk-actions/{request_id}` until `status` is terminal, then page through `items`. `Idempotency-Key` is the durable `request_id`, scoped per profile. Reusing the same key returns the current record (202 while queued or running; 200 when terminal); request bodies are not fingerprinted, so a reused key with a different body returns the original record. The static required scope is `campaigns:write` only because the actual scope is derived from the request body.\n\nScope table (v1):\n\n| `entity_type` | non-archive actions | `archived` |\n|---|---|---|\n| `campaigns` | `campaigns:write` | `campaigns:archive` (NEW) |\n| `ad_groups` | `ad_groups:write` | `ad_groups:archive` |\n| `keywords`, `targets` | `targets:write` | `targets:archive` |\n| `product_ads` | `ads:write` | `ads:archive` |\n| `negative_keywords`, `negative_targets`, `campaign_negative_keywords` | `negative-targets:write` | `negative-targets:archive` (NEW) |\n| `GET /bulk-actions/{request_id}` | `bulk_actions:read` (NEW) | |\n\nUnsupported operations: portfolio moves, dates, bid strategy, placements, creates, recipes, local-only actions, and search terms.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "campaigns:write", "x-merchjar-derived-required-scopes": [ "campaigns:write", "campaigns:archive", "ad_groups:write", "ad_groups:archive", "targets:write", "targets:archive", "ads:write", "ads:archive", "negative-targets:write", "negative-targets:archive" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Durable request_id, scoped per profile. The body is not fingerprinted; reusing this key returns the current record.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,64}$" }, "example": "abc-123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id", "entity_type", "entity_ids", "action" ], "properties": { "profile_id": { "$ref": "#/components/schemas/BigIntString" }, "entity_type": { "type": "string", "enum": [ "campaigns", "ad_groups", "keywords", "targets", "product_ads", "negative_keywords", "negative_targets", "campaign_negative_keywords" ] }, "entity_ids": { "type": "array", "minItems": 1, "maxItems": 50000, "uniqueItems": true, "items": { "$ref": "#/components/schemas/BigIntString" } }, "action": { "oneOf": [ { "$ref": "#/components/schemas/BulkActionSetState" }, { "$ref": "#/components/schemas/BulkActionSetDailyBudget" }, { "$ref": "#/components/schemas/BulkActionAdjustDailyBudget" }, { "$ref": "#/components/schemas/BulkActionSetBid" }, { "$ref": "#/components/schemas/BulkActionAdjustBid" }, { "$ref": "#/components/schemas/BulkActionSetDefaultBid" } ], "discriminator": { "propertyName": "type" } } }, "additionalProperties": false }, "example": { "profile_id": "123456789012345", "entity_type": "keywords", "entity_ids": [ "11111111111111", "22222222222222" ], "action": { "type": "set_state", "state": "paused" } } } } }, "responses": { "200": { "description": "A replay of a terminal request, including the first page of items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionTerminalResponse" }, "examples": { "partial": { "summary": "Partially completed action", "value": { "data": { "request_id": "abc-123", "profile_id": "123456789012345", "entity_type": "keywords", "action": { "type": "set_state", "state": "paused" }, "status": "partial", "reason_code": null, "counts": { "requested": 3, "succeeded": 1, "failed": 1, "unchanged": 1, "skipped_archived": 0, "skipped_invalid": 0 }, "items": [ { "entity_id": "11111111111111", "status": "succeeded" }, { "entity_id": "22222222222222", "status": "failed", "error": { "code": "amazon_error", "message": "Amazon rejected the state change" } }, { "entity_id": "33333333333333", "status": "unchanged" } ], "created_at": "2026-09-04T10:00:00Z", "started_at": "2026-09-04T10:00:01Z", "completed_at": "2026-09-04T10:00:03Z" }, "pagination": { "page": 1, "per_page": 1000, "total": 3, "last_page": 1 } } } } } } }, "202": { "description": "Accepted and queued, including replay while queued or running. Poll the Location until the status is terminal.", "headers": { "Location": { "description": "Profile-scoped bulk-action status resource.", "schema": { "type": "string", "format": "uri-reference" }, "example": "/api/v5/bulk-actions/abc-123" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionAcceptedResponse" }, "examples": { "queued": { "summary": "Queued action", "value": { "data": { "request_id": "abc-123", "profile_id": "123456789012345", "entity_type": "keywords", "action": { "type": "set_state", "state": "paused" }, "status": "queued", "reason_code": null, "counts": null, "created_at": "2026-09-04T10:00:00Z", "started_at": null, "completed_at": null } } } } } } }, "400": { "description": "The request is invalid, has duplicate entity IDs, or uses an unsupported action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid_request": { "value": { "error": { "code": "invalid_request", "message": "profile_id must be a positive decimal string" } } }, "duplicate_entity_ids": { "value": { "error": { "code": "duplicate_entity_ids", "message": "entity_ids must be unique" } } }, "unsupported_action": { "value": { "error": { "code": "unsupported_action", "message": "set_state is not supported for this entity type" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "description": "More than 50,000 entity IDs were supplied or the body exceeds 4 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "too_many_entities", "message": "entity_ids may contain at most 50000 IDs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "The service is draining; retry after the supplied delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "draining", "message": "Bulk action service is draining" } } } } } } } }, "/bulk-actions/{request_id}": { "get": { "operationId": "getBulkAction", "tags": [ "Bulk actions" ], "summary": "Retrieve bulk action", "description": "Retrieves a submitted bulk action without resuming it. While the status is `queued` or `running`, it returns 202 with no items and null counts. Once terminal, it returns 200 and a page of items.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "bulk_actions:read", "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" }, { "name": "request_id", "in": "path", "required": true, "description": "The Idempotency-Key used to submit the bulk action.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,64}$" }, "example": "abc-123" }, { "name": "page", "in": "query", "required": false, "description": "One-based item page number. Defaults to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page. Defaults to 1000; values above 1000 are capped at 1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } } ], "responses": { "200": { "description": "A terminal bulk action job record and a page of items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionTerminalResponse" } } } }, "202": { "description": "The bulk action is queued or running; poll again after Retry-After. Items are omitted and counts is null.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionAcceptedResponse" }, "examples": { "running": { "summary": "Running action", "value": { "data": { "request_id": "abc-123", "profile_id": "123456789012345", "entity_type": "keywords", "action": { "type": "set_state", "state": "paused" }, "status": "running", "reason_code": null, "counts": null, "created_at": "2026-09-04T10:00:00Z", "started_at": "2026-09-04T10:00:01Z", "completed_at": null } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No public bulk action exists for this profile and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Bulk action not found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/campaigns": { "post": { "operationId": "createSponsoredProductsCampaigns", "tags": [ "Campaign creation" ], "summary": "Create Sponsored Products campaigns", "description": "Creates between 1 and 1,000 Sponsored Products campaigns for the API-key-authorized `profileid` header. The request schema is strict: `profile_id` and every other undeclared field are rejected before MerchJar calls Amazon. The 200 response is Amazon's raw batch envelope, without a MerchJar wrapper. A `success` or `partialSuccess` result queues local projection; browse data is eventually consistent and the response does not report projection completion. An error-only Amazon envelope is also passed through, but does not queue a receipt. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This router does not currently install the API-key rate limit middleware, so it does not emit the standard rate limit headers or 429/503 rate limit responses.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "campaigns:write", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Positive PostgreSQL signed-bigint Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.", "schema": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6][0-9]{0}|9223372036854775807)$", "example": "9007199254740993" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "campaigns" ], "properties": { "campaigns": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "required": [ "adProduct", "name", "state", "marketplaceScope", "marketplaces", "startDateTime", "budgets", "autoCreationSettings" ], "properties": { "adProduct": { "const": "SPONSORED_PRODUCTS" }, "name": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ] }, "marketplaceScope": { "const": "SINGLE_MARKETPLACE" }, "marketplaces": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "enum": [ "AE", "AU", "BE", "BR", "CA", "DE", "EG", "ES", "FR", "GB", "IN", "IT", "JP", "MX", "NL", "PL", "SA", "SE", "SG", "TR", "US" ] } }, "startDateTime": { "type": "string", "format": "date-time" }, "budgets": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "budgetType", "budgetValue", "recurrenceTimePeriod" ], "properties": { "budgetType": { "const": "MONETARY" }, "budgetValue": { "type": "object", "required": [ "monetaryBudgetValue" ], "properties": { "monetaryBudgetValue": { "type": "object", "required": [ "monetaryBudget" ], "properties": { "monetaryBudget": { "type": "object", "required": [ "value", "currencyCode" ], "properties": { "value": { "type": "number", "exclusiveMinimum": 0 }, "currencyCode": { "type": "string", "enum": [ "AED", "AUD", "BRL", "CAD", "EGP", "EUR", "GBP", "INR", "JPY", "MXN", "PLN", "SAR", "SEK", "SGD", "TRY", "USD" ] } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "recurrenceTimePeriod": { "const": "DAILY" } }, "additionalProperties": false } }, "autoCreationSettings": { "type": "object", "required": [ "autoCreateTargets", "autoManageCampaign" ], "properties": { "autoCreateTargets": { "type": "boolean" }, "autoManageCampaign": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Amazon's raw batch-create envelope. At least one non-empty `success`, `partialSuccess`, or `error` array is present. Fields inside each Amazon result item are passed through unchanged and may evolve with Amazon's API.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": {} }, "partialSuccess": { "type": "array", "items": {} }, "error": { "type": "array", "items": {} } }, "anyOf": [ { "required": [ "success" ], "properties": { "success": { "minItems": 1 } } }, { "required": [ "partialSuccess" ], "properties": { "partialSuccess": { "minItems": 1 } } }, { "required": [ "error" ], "properties": { "error": { "minItems": 1 } } } ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON or strict create schema (`invalid_request`), an invalid `profileid` (`invalid_profile_id`), or a request that reaches the handler without trusted profile context (`missing_profile_context`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "invalid_profile_id", "missing_profile_context" ] }, "message": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Amazon transport failed or returned an envelope with no non-empty `success`, `partialSuccess`, or `error` array. The campaign create may have reached Amazon; MerchJar does not retry it. Check Amazon before retrying.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "public_create_outcome_unknown" }, "message": { "const": "Campaign creation outcome is unknown; check Amazon before retrying" } }, "additionalProperties": false } }, "additionalProperties": false } } } } } } }, "/campaigns/{id}": { "patch": { "operationId": "updateSponsoredProductsCampaignSettings", "tags": [ "Campaign creation" ], "summary": "Update Sponsored Products campaign settings", "description": "Updates supplied Sponsored Products name, daily budget, bidding strategy, and/or placement adjustments for the API-key-authorized profile. The body is strict and sparse: omitted settings are not cleared. MerchJar passes Amazon's raw update envelope through unchanged and never retries an uncertain write.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "campaigns:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Positive Amazon campaign ID as a decimal string; do not send a JavaScript number.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740993" }, { "name": "profileid", "in": "header", "required": true, "description": "Positive PostgreSQL signed-bigint Amazon Advertising profile ID owned by the API key.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740993" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required 1-64 character opaque request identifier for durable, idempotent updates.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "name" ] }, { "required": [ "budgets" ] }, { "required": [ "optimizations" ] } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "budgets": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "budgetType", "budgetValue", "recurrenceTimePeriod" ], "additionalProperties": false, "properties": { "budgetType": { "const": "MONETARY" }, "budgetValue": { "type": "object", "required": [ "monetaryBudgetValue" ], "additionalProperties": false, "properties": { "monetaryBudgetValue": { "type": "object", "required": [ "monetaryBudget" ], "additionalProperties": false, "properties": { "monetaryBudget": { "type": "object", "required": [ "value", "currencyCode" ], "additionalProperties": false, "properties": { "value": { "type": "number", "exclusiveMinimum": 0, "multipleOf": 0.01, "maximum": 21474836.47 }, "currencyCode": { "type": "string" } } } } } } }, "recurrenceTimePeriod": { "const": "DAILY" } } } }, "optimizations": { "type": "object", "required": [ "bidSettings" ], "additionalProperties": false, "properties": { "bidSettings": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "bidStrategy" ] }, { "required": [ "bidAdjustments" ] } ], "properties": { "bidStrategy": { "type": "string", "enum": [ "SALES_DOWN_ONLY", "SALES_UP_AND_DOWN", "MANUAL" ] }, "bidAdjustments": { "type": "object", "required": [ "placementBidAdjustments" ], "additionalProperties": false, "properties": { "placementBidAdjustments": { "type": "array", "description": "Each placement value may appear at most once.", "minItems": 1, "maxItems": 3, "items": { "type": "object", "required": [ "placement", "percentage" ], "additionalProperties": false, "properties": { "placement": { "type": "string", "enum": [ "TOP_OF_SEARCH", "REST_OF_SEARCH", "PRODUCT_PAGE" ] }, "percentage": { "type": "integer", "minimum": 0, "maximum": 900 } } } } } } } } } } } } } } }, "responses": { "200": { "description": "Amazon's raw batch-update envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid campaign ID, JSON, strict request body, or trusted profile context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "An API key is required for this mutation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "The Idempotency-Key identifies an error-only, incomplete, or legacy public update whose raw Amazon response cannot be replayed safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Amazon transport failed or returned an unusable envelope. The update may have reached Amazon; check Amazon before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/custom-fields/csv/imports/{entityType}": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "post": { "operationId": "createCustomFieldCsvImport", "tags": [ "Custom fields" ], "summary": "Import custom field CSV", "description": "Queues a CSV import for the selected entity type. The request body must be UTF-8 `text/csv` and no larger than 25 MiB. Set `dry_run=true` to validate without applying mutations.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:write", "parameters": [ { "$ref": "#/components/parameters/CustomFieldEntityType" }, { "name": "dry_run", "in": "query", "schema": { "type": "boolean" }, "example": false } ], "requestBody": { "required": true, "content": { "text/csv": { "schema": { "type": "string" }, "example": "entity_id,field,value\n9007199254740995,Priority,high\n" } } }, "responses": { "202": { "$ref": "#/components/responses/CustomFieldJobAccepted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "description": "CSV upload exceeds 25 MiB." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/csv/exports/{entityType}": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "post": { "operationId": "createCustomFieldCsvExport", "tags": [ "Custom fields" ], "summary": "Export custom field CSV", "description": "Queues a CSV export for the selected entity type.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "name": "entityType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CustomFieldEntityType" }, "example": "campaign" } ], "responses": { "202": { "$ref": "#/components/responses/CustomFieldJobAccepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/csv/jobs/{jobId}": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "get": { "operationId": "getCustomFieldCsvJob", "tags": [ "Custom fields" ], "summary": "Retrieve CSV job", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "job_01HXYZ" } ], "responses": { "200": { "$ref": "#/components/responses/CustomFieldJob" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/csv/jobs/{jobId}/cancel": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "post": { "operationId": "cancelCustomFieldCsvJob", "tags": [ "Custom fields" ], "summary": "Cancel CSV job", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:write", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "job_01HXYZ" } ], "responses": { "200": { "$ref": "#/components/responses/CustomFieldJob" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/csv/jobs/{jobId}/errors": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "get": { "operationId": "downloadCustomFieldCsvErrors", "tags": [ "Custom fields" ], "summary": "Download CSV errors", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "$ref": "#/components/parameters/CustomFieldJobId" } ], "responses": { "200": { "description": "CSV error artifact.", "content": { "text/csv": { "schema": { "type": "string" }, "example": "row,error\n2,invalid value\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Artifact not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/csv/jobs/{jobId}/download": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "get": { "operationId": "downloadCustomFieldCsv", "tags": [ "Custom fields" ], "summary": "Download CSV export", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "$ref": "#/components/parameters/CustomFieldJobId" } ], "responses": { "200": { "description": "CSV artifact.", "content": { "text/csv": { "schema": { "type": "string" }, "example": "entity_id,field,value\n9007199254740995,Priority,high\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Artifact not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/catalog/{entityType}": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "get": { "operationId": "getCustomFieldCatalog", "tags": [ "Custom fields" ], "summary": "Retrieve field catalog", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "$ref": "#/components/parameters/CustomFieldEntityType" } ], "responses": { "200": { "description": "Definitions and profile quota usage.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "version": "1", "definitions": [], "definition_count": 0, "value_count": 0 } } } }, "304": { "description": "Catalog unchanged." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/values/{entityType}/snapshot": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "post": { "operationId": "snapshotCustomFieldValues", "tags": [ "Custom fields" ], "summary": "Snapshot field values", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "$ref": "#/components/parameters/CustomFieldEntityType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_ids" ], "properties": { "entity_ids": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BigIntString" } } } }, "example": { "entity_ids": [ "9007199254740995" ] } } } }, "responses": { "200": { "$ref": "#/components/responses/CustomFieldData" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/definitions": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "post": { "operationId": "createCustomFieldDefinition", "tags": [ "Custom fields" ], "summary": "Create field definition", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionCreate" }, "example": { "entity_type": "campaign", "name": "Priority", "data_type": 1 } } } }, "responses": { "201": { "$ref": "#/components/responses/CustomFieldDefinition" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Definition conflict, quota exceeded, or active dependants." }, "422": { "description": "Invalid definition." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/definitions/{definitionId}": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "patch": { "operationId": "updateCustomFieldDefinition", "tags": [ "Custom fields" ], "summary": "Update field definition", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:write", "parameters": [ { "$ref": "#/components/parameters/CustomFieldDefinitionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionUpdate" }, "example": { "entity_type": "campaign", "expected_version": "1", "name": "Priority" } } } }, "responses": { "200": { "$ref": "#/components/responses/CustomFieldDefinition" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Definition not found." }, "409": { "description": "Definition conflict." }, "422": { "description": "Invalid definition." }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteCustomFieldDefinition", "tags": [ "Custom fields" ], "summary": "Delete field definition", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:write", "parameters": [ { "$ref": "#/components/parameters/CustomFieldDefinitionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionDelete" }, "example": { "entity_type": "campaign", "expected_version": "1" } } } }, "responses": { "200": { "$ref": "#/components/responses/CustomFieldData" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Definition not found." }, "409": { "description": "Definition conflict or active dependants." }, "422": { "description": "Invalid deletion request." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/values/{entityType}": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "get": { "operationId": "listCustomFieldValues", "tags": [ "Custom fields" ], "summary": "List field values", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "$ref": "#/components/parameters/CustomFieldEntityType" }, { "name": "entity_id", "in": "query", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740995" }, { "name": "entity_ids", "in": "query", "schema": { "type": "string" }, "example": "9007199254740995,9007199254740996" } ], "responses": { "200": { "$ref": "#/components/responses/CustomFieldData" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/values/{entityType}/definition/{definitionId}": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "get": { "operationId": "listCustomFieldValuesForDefinition", "tags": [ "Custom fields" ], "summary": "List definition values", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "$ref": "#/components/parameters/CustomFieldEntityType" }, { "$ref": "#/components/parameters/CustomFieldDefinitionId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "example": 100 }, { "name": "after_entity_id", "in": "query", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740995" } ], "responses": { "200": { "$ref": "#/components/responses/CustomFieldData" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/values/{entityType}/bulk": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "post": { "operationId": "mutateCustomFieldValues", "tags": [ "Custom fields" ], "summary": "Update field values", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:write", "parameters": [ { "$ref": "#/components/parameters/CustomFieldEntityType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldBulkMutation" }, "example": { "mutations": [ { "field_definition_id": "1", "entity_id": "9007199254740995", "operation": "set", "value": "high" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/CustomFieldData" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Invalid value mutation." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/values/{entityType}/{entityId}/history": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "get": { "operationId": "listCustomFieldValueHistory", "tags": [ "Custom fields" ], "summary": "List field value history", "description": "Returns history newest-first by `(created_at, id)`. To fetch the next page, send `before_id` equal to the final history `id` from the previous response; the cursor is excluded, so the next response contains older history. Preserve `definition_id` when it was used on the first request. For example, first request: `/custom-fields/values/campaign/9007199254740995/history?definition_id=9007199254740997&limit=2`; if its final history `id` is `9007199254741999`, second request: `/custom-fields/values/campaign/9007199254740995/history?definition_id=9007199254740997&limit=2&before_id=9007199254741999`. A supplied cursor that does not match history in this request scope returns empty history.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:read", "parameters": [ { "$ref": "#/components/parameters/CustomFieldEntityType" }, { "name": "entityId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740995" }, { "name": "definition_id", "in": "query", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "1" }, { "name": "before_id", "in": "query", "description": "The final history ID from the preceding page, sent as a decimal string.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254741999" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "example": 100 } ], "responses": { "200": { "$ref": "#/components/responses/CustomFieldData" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/custom-fields/history/{historyId}/rollback": { "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" } ], "post": { "operationId": "rollbackCustomFieldHistory", "tags": [ "Custom fields" ], "summary": "Roll back field change", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "custom_fields:write", "parameters": [ { "name": "historyId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "expected_version" ], "properties": { "entity_type": { "$ref": "#/components/schemas/CustomFieldEntityType" }, "expected_version": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } }, "example": { "entity_type": "campaign", "expected_version": "1" } } } }, "responses": { "200": { "$ref": "#/components/responses/CustomFieldData" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "History entry not found." }, "409": { "description": "Version conflict." }, "422": { "description": "Invalid rollback request." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/{entity_type}/{entity_id}": { "get": { "operationId": "listEntityHistory", "tags": [ "History" ], "summary": "List entity changes", "description": "Returns the profile-scoped legacy bid-history stream, newest first with `hash` as the tie-breaker. MerchJar selects the change type from `entity_type`: campaign budgets, ad-group default bids, and keyword or target bids.", "x-merchjar-required-scope": "history:read", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Positive decimal Amazon Advertising profile ID owned by the API-key user.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "maxLength": 19, "example": "9007199254740993" } }, { "name": "entity_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "campaigns", "ad_groups", "keywords", "targets" ] } }, { "name": "entity_id", "in": "path", "required": true, "description": "Positive PostgreSQL-signed-bigint entity ID encoded as a decimal string (maximum `9223372036854775807`).", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$", "maxLength": 19, "example": "9007199254740997" } }, { "name": "page", "in": "query", "required": false, "description": "One-based page number. Missing, non-positive, or non-numeric values fall back to 1; values above 21474836 are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 21474836, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page. Missing, non-positive, or non-numeric values fall back to 25; values above 100 are capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "A paginated history result. Empty history is represented by an empty data array.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "entity_id", "entity_type", "change_type", "previous_value", "new_value", "timestamp", "hash", "profile_id" ], "properties": { "entity_id": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Entity ID serialized as a decimal string." }, "entity_type": { "type": "string", "enum": [ "campaigns", "ad_groups", "keywords", "targets" ] }, "change_type": { "type": "string", "enum": [ "BUDGET_AMOUNT", "DEFAULT_BID_AMOUNT", "BID_AMOUNT" ] }, "previous_value": { "type": [ "string", "null" ], "description": "Previous numeric value (as a decimal string) or previous string value." }, "new_value": { "type": [ "string", "null" ], "description": "New numeric value (as a decimal string) or new string value." }, "timestamp": { "type": "string", "description": "History timestamp serialized from the database bigint." }, "hash": { "type": "string", "description": "History hash serialized from the database bigint; it is the deterministic tie-breaker for equal timestamps." }, "profile_id": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Profile ID serialized as a decimal string." } }, "additionalProperties": false } }, "pagination": { "type": "object", "required": [ "page", "per_page", "total", "last_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "last_page": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "The history query failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "internal_error" }, "message": { "const": "Failed to list bid history" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/negative-targets": { "post": { "operationId": "createSponsoredProductsNegativeProductTargets", "tags": [ "Target creation" ], "summary": "Create negative targets", "description": "Creates between 1 and 1,000 negative Sponsored Products product targets for the API-key-authorized `profileid` header. Each target must have an ad-group parent, `negative: true`, `targetType: PRODUCT`, `PRODUCT_EXACT` matching, and an ASIN. The request schema is strict: unknown fields are rejected before MerchJar calls Amazon. A `success` or `partialSuccess` result queues local projection; an error-only envelope does not. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This endpoint does not install the standard API-key rate limit middleware, so it does not emit the standard rate limit headers or standard `429` or `503` rate limit responses.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "negative-targets:write", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Positive Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740993" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A batch of negative Sponsored Products product targets.", "required": [ "targets" ], "properties": { "targets": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "required": [ "adGroupId", "adProduct", "negative", "state", "targetType", "targetDetails" ], "properties": { "adGroupId": { "$ref": "#/components/schemas/BigIntString" }, "adProduct": { "const": "SPONSORED_PRODUCTS" }, "negative": { "const": true }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ] }, "targetType": { "const": "PRODUCT" }, "targetDetails": { "type": "object", "required": [ "productTarget" ], "properties": { "productTarget": { "type": "object", "required": [ "matchType", "productId", "productIdType" ], "properties": { "matchType": { "const": "PRODUCT_EXACT" }, "productId": { "type": "string", "minLength": 1, "description": "ASIN to exclude." }, "productIdType": { "const": "ASIN" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false }, "examples": { "negativeProductTarget": { "summary": "Exclude an ASIN from an ad group", "value": { "targets": [ { "adGroupId": "9007199254740995", "adProduct": "SPONSORED_PRODUCTS", "negative": true, "state": "ENABLED", "targetType": "PRODUCT", "targetDetails": { "productTarget": { "matchType": "PRODUCT_EXACT", "productId": "B012345678", "productIdType": "ASIN" } } } ] } } } } } }, "responses": { "200": { "description": "Amazon's raw batch-create envelope. At least one non-empty `success`, `partialSuccess`, or `error` array is present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmazonBatchCreateEnvelope" } } } }, "400": { "description": "Invalid JSON or an invalid strict negative-target-create request, profile ID, or profile context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Invalid Sponsored Products negative target create request" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Amazon transport failed or returned no recognised result array. Negative target creation may have reached Amazon; check Amazon before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "public_create_outcome_unknown", "message": "Negative target creation outcome is unknown; check Amazon before retrying" } } } } } } } }, "/product-ads": { "post": { "operationId": "createSponsoredProductsProductAds", "tags": [ "Product ad creation" ], "summary": "Create product ads", "description": "Creates between 1 and 1,000 Sponsored Products product ads for the API-key-authorized `profileid` header. This is deliberately not generic unified-v1 ad creation: each item supports only `PRODUCT_AD` with exactly one `productCreative` / `advertisedProduct` creative. The request schema is strict: `profile_id`, marketplace/global-store identity, headline, and every other undeclared field are rejected before MerchJar calls Amazon. The 200 response is Amazon's raw batch envelope, without a MerchJar wrapper. A `success` or `partialSuccess` result queues local projection; browse data is eventually consistent and the response does not report projection completion. An error-only Amazon envelope is also passed through, but does not queue a receipt. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This router does not currently install the API-key rate limit middleware, so it does not emit the standard rate limit headers or 429/503 rate limit responses.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "ads:write", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Positive PostgreSQL signed-bigint Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.", "schema": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6][0-9]{0}|9223372036854775807)$", "example": "9007199254740993" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ads" ], "properties": { "ads": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "required": [ "adProduct", "adType", "adGroupId", "state", "creative" ], "properties": { "adProduct": { "const": "SPONSORED_PRODUCTS" }, "adType": { "const": "PRODUCT_AD" }, "adGroupId": { "type": "string", "description": "Positive PostgreSQL signed-bigint Amazon ad-group ID encoded as a decimal string, never a JavaScript number.", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6][0-9]{0}|9223372036854775807)$", "example": "9007199254740995" }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ] }, "creative": { "type": "object", "required": [ "productCreative" ], "properties": { "productCreative": { "type": "object", "required": [ "productCreativeSettings" ], "properties": { "productCreativeSettings": { "type": "object", "required": [ "advertisedProduct" ], "properties": { "advertisedProduct": { "type": "object", "required": [ "productId", "productIdType" ], "properties": { "productId": { "type": "string", "minLength": 1 }, "productIdType": { "type": "string", "enum": [ "ASIN", "SKU" ] } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Amazon's raw batch-create envelope. At least one non-empty `success`, `partialSuccess`, or `error` array is present. Fields inside each Amazon result item are passed through unchanged and may evolve with Amazon's API.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": {} }, "partialSuccess": { "type": "array", "items": {} }, "error": { "type": "array", "items": {} } }, "anyOf": [ { "required": [ "success" ], "properties": { "success": { "minItems": 1 } } }, { "required": [ "partialSuccess" ], "properties": { "partialSuccess": { "minItems": 1 } } }, { "required": [ "error" ], "properties": { "error": { "minItems": 1 } } } ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON or strict create schema (`invalid_request`), an invalid `profileid` (`invalid_profile_id`), or a request that reaches the handler without trusted profile context (`missing_profile_context`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "invalid_profile_id", "missing_profile_context" ] }, "message": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Amazon transport failed or returned an envelope with no non-empty `success`, `partialSuccess`, or `error` array. The product-ad create may have reached Amazon; MerchJar does not retry it. Check Amazon before retrying.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "public_create_outcome_unknown" }, "message": { "const": "Product ad creation outcome is unknown; check Amazon before retrying" } }, "additionalProperties": false } }, "additionalProperties": false } } } } } } }, "/product-ads/{id}": { "patch": { "operationId": "updateSponsoredProductsProductAd", "tags": [ "Product ad creation" ], "summary": "Update a product ad", "description": "Updates only `state` for one Sponsored Products product ad. An `Idempotency-Key` is required.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "ads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "example": "9007199254740995", "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "profileid", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "enum": [ "ENABLED", "PAUSED" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Amazon raw update envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Product ad not found" }, "502": { "description": "Outcome unknown; verify Amazon before retrying" } } }, "delete": { "operationId": "archiveSponsoredProductsProductAd", "tags": [ "Product ad creation" ], "summary": "Delete a product ad", "description": "Archives one Sponsored Products product ad and verifies the terminal state; Amazon may omit an archived product ad from read-back. An Idempotency-Key is required.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "ads:archive", "parameters": [ { "name": "id", "in": "path", "required": true, "example": "9007199254740995", "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "profileid", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Amazon raw delete envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Product ad not found" }, "409": { "description": "Product ad is already archived" }, "502": { "description": "Outcome unknown; verify Amazon before retrying" } } } }, "/profiles": { "get": { "operationId": "listProfiles", "tags": [ "Profiles" ], "summary": "List profiles", "description": "Returns profiles owned by the API key's user. This operation does not require a `profileid` header; it is the operation used to discover profile IDs for later profile-scoped requests.", "x-merchjar-required-scope": "profiles:read", "responses": { "200": { "description": "The accessible profiles, ordered by profile ID. An API-key user with no keys record or no profiles receives an empty data array.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "profile_id", "name", "nickname", "country_code", "currency_code", "marketplace_id", "timezone", "type", "managed", "ad_spend_30d", "ad_spend_30d_usd" ], "properties": { "profile_id": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Positive decimal profile ID. It is serialized as a string to preserve bigint precision.", "example": "9007199254740993" }, "name": { "type": [ "string", "null" ], "description": "Amazon account name when available." }, "nickname": { "type": [ "string", "null" ], "description": "User-assigned MerchJar profile nickname when available." }, "country_code": { "type": "string", "description": "Amazon Advertising country code." }, "currency_code": { "type": "string", "description": "Amazon Advertising currency code." }, "marketplace_id": { "type": "string", "description": "Amazon marketplace identifier." }, "timezone": { "type": "string", "description": "Profile timezone." }, "type": { "type": "string", "description": "Amazon Advertising profile type." }, "managed": { "type": "boolean", "description": "Whether MerchJar is actively managing the profile." }, "ad_spend_30d": { "type": "number", "description": "Total ad spend over the preceding 30 days in local-currency cents." }, "ad_spend_30d_usd": { "type": "number", "description": "Total ad spend over the preceding 30 days in USD cents." } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/segments/validate": { "post": { "operationId": "validateSegment", "tags": [ "Segments" ], "summary": "Validate a segment trigger", "description": "Compiles a Segment DSL trigger without executing it. `profile_id` is optional unless the trigger references custom fields; when supplied, the API key must own that profile.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:validate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trigger", "ad_type" ], "properties": { "trigger": { "type": "string", "minLength": 1, "description": "Segment DSL expression to compile." }, "ad_type": { "type": "string", "minLength": 1, "description": "Segment entity type. Input is case- and separator-insensitive; see the endpoint description for supported values." }, "profile_id": { "$ref": "#/components/schemas/BigIntString", "description": "Required when validating a trigger that references custom fields." } } } } } }, "responses": { "200": { "description": "The trigger is valid.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "variables" ], "properties": { "valid": { "const": true }, "variables": { "type": "object", "description": "Map of DSL variable names to inferred types.", "additionalProperties": { "type": "string" } } } }, "example": { "valid": true, "variables": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "The trigger does not compile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "error" ], "properties": { "valid": { "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Usually `parse_error`; compiler error types are preserved." }, "message": { "type": "string" }, "position": { "type": "integer", "minimum": 0 } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A required execution dependency is temporarily unavailable or the service is draining.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/segments/preview": { "post": { "operationId": "previewSegment", "tags": [ "Segments" ], "summary": "Preview segment matches", "description": "Evaluates a Segment DSL trigger for a profile without persisting a segment. Preview rows depend on `ad_type`; every returned field whose name ends in `_id` is serialized as a decimal string. In addition to the API-key per-minute limiter, preview uses an account-level burst-admission limiter.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:preview", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id", "trigger", "ad_type", "action", "action_params" ], "properties": { "profile_id": { "$ref": "#/components/schemas/BigIntString" }, "trigger": { "type": "string", "minLength": 1, "description": "Segment DSL expression." }, "ad_type": { "type": "string", "minLength": 1, "description": "One of campaigns, ad_groups, ads (or accepted alias product_ads), keywords, targets, keywords_and_targets, search_terms, placements, or a negative type. Input is case- and separator-insensitive. Negative types are preview-only." }, "action": { "type": "string", "minLength": 1, "description": "One of set_state, set_budget, set_default_bid, set_bid, or create_negatives. Input is case- and separator-insensitive." }, "action_params": { "type": "object", "description": "Action parameters. For set_state, `value` must be a number or numeric string (default 2). For set_budget, set_default_bid, and set_bid, `direction` defaults to `set-to-$`, `value` defaults to 0, and `source` defaults to `value`; `source: variable` makes `value` a DSL variable name. create_negatives accepts an empty object." }, "page": { "type": "integer", "minimum": 1, "default": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } } } } }, "responses": { "200": { "description": "The matching page and aggregate metrics.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit", "description": "The active preview burst capacity." }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining", "description": "Remaining preview admissions in the account-level burst bucket." }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset", "description": "Unix timestamp in seconds for the next preview admission refill." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "totals", "meta" ], "properties": { "data": { "type": "array", "description": "Entity rows. Columns vary by ad type and selected trigger metrics.", "items": { "type": "object", "properties": { "campaign_settings": { "type": "object", "description": "Present for rows with a campaign parent.", "properties": { "bid_strategy": { "type": [ "string", "null" ] }, "placement_adjustments": { "type": "object", "required": [ "top_of_search", "rest_of_search", "product_page", "home_page" ], "properties": { "top_of_search": { "type": [ "number", "null" ], "description": "Raw percentage points." }, "rest_of_search": { "type": [ "number", "null" ], "description": "Raw percentage points." }, "product_page": { "type": [ "number", "null" ], "description": "Raw percentage points." }, "home_page": { "type": [ "number", "null" ], "description": "Raw percentage points." } } } } } }, "additionalProperties": true } }, "pagination": { "type": "object", "required": [ "page", "per_page", "total", "last_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "last_page": { "type": "integer", "minimum": 0, "description": "0 when no rows match; otherwise the final 1-based page." } } }, "totals": { "type": "object", "description": "Aggregate metrics over all matching rows, not only this page.", "additionalProperties": { "type": "number" } }, "meta": { "type": "object", "required": [ "time_periods", "variables" ], "properties": { "time_periods": { "type": "array", "items": { "type": "string" } }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A client-disconnected or superseded preview query was cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "preview_superseded", "message": "Preview was superseded" } } } } }, "422": { "description": "A trigger or campaign budget policy is semantically invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Preview generation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/segments": { "get": { "operationId": "listSegments", "tags": [ "Segments" ], "summary": "List segments", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:read", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Amazon Advertising profile ID owned by the API key.", "schema": { "$ref": "#/components/schemas/BigIntString" } } ], "responses": { "200": { "description": "All active v2 segments for the profile.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/paths/~1segments~1{id}/get/responses/200/content/application~1json/schema/properties/data" } } } }, "example": { "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Listing segments failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } }, "post": { "operationId": "createSegment", "tags": [ "Segments" ], "summary": "Create a segment", "description": "Creates a v2 segment for the body `profile_id`; it must belong to the API key. Run [POST /segments/validate](#tag/Segments/operation/validateSegment) and [POST /segments/preview](#tag/Segments/operation/previewSegment) first to check the trigger and matching entities. Negative segment types can be previewed but cannot be persisted.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id", "name", "trigger", "ad_type", "action" ], "properties": { "profile_id": { "$ref": "#/components/schemas/BigIntString" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "trigger": { "type": "string", "minLength": 1 }, "ad_type": { "type": "string", "minLength": 1, "description": "A writable ad type: campaigns, ad_groups, ads (or accepted alias product_ads), keywords, targets, keywords_and_targets, search_terms, or placements. Input is case- and separator-insensitive." }, "action": { "type": "string", "minLength": 1, "description": "set_state, set_budget, set_default_bid, set_bid, or create_negatives. Input is case- and separator-insensitive." }, "action_params": { "type": "object", "default": {}, "description": "See preview action_params semantics. Unknown properties are ignored by the request parser." }, "frequency": { "type": "string", "default": "daily", "description": "Writable values are `after_every_data_sync`, `daily`, `weekly`, `monthly`, and `manual`. `scheduled` is rejected with `422 schedule_required` unless the segment already has a schedule, when it is a no-op. A non-`scheduled` value on a scheduled segment removes the clock schedule and skips future runs. Input is case- and separator-insensitive; `manually` aliases `manual`. Weekly and monthly use today's date as their anchor whenever applied." }, "enabled": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "The created segment.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/paths/~1segments~1{id}/get/responses/200/content/application~1json/schema/properties/data" } } }, "example": { "data": { "id": "9007199254740997", "profile_id": "9007199254740993", "name": "Pause low-performing targets", "enabled": true, "ad_type": "targets", "trigger": "clicks > 20", "action": "set_state", "action_params": { "value": 2 }, "frequency": "daily", "last_run": null, "created_at": "2026-08-29T12:00:00Z", "updated_at": "2026-08-29T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "The trigger does not compile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Creating the segment failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/segments/{id}/run": { "post": { "operationId": "runSegment", "tags": [ "Segments" ], "summary": "Create segment run", "description": "Runs the segment synchronously and returns its completed result. It works for disabled segments and does not enable the segment or change its schedule. A 202 response means the existing executor is still processing the run.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:write", "parameters": [ { "$ref": "#/components/parameters/SegmentId" }, { "$ref": "#/components/parameters/ProfileIdHeader" } ], "responses": { "200": { "description": "Run completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "uuid", "result" ], "properties": { "uuid": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } }, "example": { "uuid": "11111111-1111-4111-8111-111111111111", "result": { "message": "Completed" } } } } }, "202": { "description": "The existing executor is still processing the run." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Segment was not found for the supplied profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Segment not found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Run could not be completed." }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/segments/{id}": { "get": { "operationId": "getSegment", "tags": [ "Segments" ], "summary": "Retrieve segment", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Segment ID. The implementation parses a signed base-10 bigint; successful segment IDs are positive decimal strings.", "schema": { "type": "string", "pattern": "^[+-]?[0-9]+$" } }, { "name": "profileid", "in": "header", "required": true, "description": "Amazon Advertising profile ID owned by the API key.", "schema": { "$ref": "#/components/schemas/BigIntString" } } ], "responses": { "200": { "description": "The segment.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "profile_id", "name", "enabled", "ad_type", "trigger", "action", "action_params", "frequency", "last_run", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/BigIntString" }, "profile_id": { "$ref": "#/components/schemas/BigIntString" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "ad_type": { "type": "string", "enum": [ "campaigns", "ad_groups", "ads", "keywords", "targets", "campaign_negative_keywords", "negative_keywords", "negative_targets", "search_terms", "placements", "keywords_and_targets", "unknown" ] }, "trigger": { "type": "string" }, "action": { "type": "string", "enum": [ "set_state", "set_budget", "set_default_bid", "set_bid", "create_negatives", "unknown" ] }, "action_params": { "type": "object", "description": "For set_state, emits `{ value }`; for set_budget, set_default_bid, or set_bid, emits `{ direction, value, source }`; create_negatives emits `{}`." }, "frequency": { "type": "string", "enum": [ "after_every_data_sync", "daily", "manual", "weekly", "monthly", "scheduled" ], "description": "Canonical returned frequency. `after_every_data_sync` runs after each sync; `daily` runs daily; `weekly` and `monthly` retain their dashboard schedule anchors but return only this canonical mode; `manual` never runs automatically and never has a clock schedule; `scheduled` is server-managed and set by `PUT /segments/{id}/schedule`. Legacy dashboard-only values return as `daily`." }, "last_run": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "example": { "data": { "id": "9007199254740997", "profile_id": "9007199254740993", "name": "Pause low-performing targets", "enabled": true, "ad_type": "targets", "trigger": "clicks > 20", "action": "set_state", "action_params": { "value": 2 }, "frequency": "daily", "last_run": null, "created_at": "2026-08-29T12:00:00Z", "updated_at": "2026-08-29T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No active v2 segment with this ID belongs to the profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Getting the segment failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } }, "patch": { "operationId": "updateSegment", "tags": [ "Segments" ], "summary": "Update a segment", "description": "Updates only supplied fields. PATCH away from `scheduled` atomically removes its clock schedule and supersedes future open runs. Negative segment types cannot be persisted.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Segment ID. The implementation parses a signed base-10 bigint; successful segment IDs are positive decimal strings.", "schema": { "type": "string", "pattern": "^[+-]?[0-9]+$" } }, { "name": "profileid", "in": "header", "required": true, "description": "Amazon Advertising profile ID owned by the API key.", "schema": { "$ref": "#/components/schemas/BigIntString" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "trigger": { "type": "string", "minLength": 1 }, "ad_type": { "type": "string", "minLength": 1, "description": "Writable segment ad type; input is case- and separator-insensitive." }, "action": { "type": "string", "minLength": 1, "description": "set_state, set_budget, set_default_bid, set_bid, or create_negatives; input is case- and separator-insensitive." }, "action_params": { "type": "object", "description": "See preview action_params semantics." }, "frequency": { "type": "string", "description": "Writable values are `after_every_data_sync`, `daily`, `weekly`, `monthly`, and `manual`. `scheduled` is rejected with `422 schedule_required` unless the segment already has a schedule, when it is a no-op. A non-`scheduled` value on a scheduled segment removes the clock schedule and skips future runs." }, "enabled": { "type": "boolean" }, "paused": { "type": "boolean", "description": "Sets or clears the segment pause timestamp. `true` skips future open scheduled runs." } } } } } }, "responses": { "200": { "description": "The updated segment.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/paths/~1segments~1{id}/get/responses/200/content/application~1json/schema/properties/data" } } }, "example": { "data": { "id": "9007199254740997", "profile_id": "9007199254740993", "name": "Pause low-performing targets", "enabled": false, "ad_type": "targets", "trigger": "clicks > 20", "action": "set_state", "action_params": { "value": 2 }, "frequency": "daily", "last_run": null, "created_at": "2026-08-29T12:00:00Z", "updated_at": "2026-08-29T12:05:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No active v2 segment with this ID belongs to the profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The trigger is invalid, `scheduled` requires a schedule, or an inactive copied schedule must be activated before enabling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Updating the segment failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } }, "delete": { "operationId": "deleteSegment", "tags": [ "Segments" ], "summary": "Delete a segment", "description": "Disables the segment, marks it deleted, clears its next schedule cursor, and skips future open scheduled runs.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Segment ID. The implementation parses a signed base-10 bigint; successful segment IDs are positive decimal strings.", "schema": { "type": "string", "pattern": "^[+-]?[0-9]+$" } }, { "name": "profileid", "in": "header", "required": true, "description": "Amazon Advertising profile ID owned by the API key.", "schema": { "$ref": "#/components/schemas/BigIntString" } } ], "responses": { "200": { "description": "The segment was deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } }, "example": { "success": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No active v2 segment with this ID belongs to the profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Deleting the segment failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/segments/{id}/schedule/timezones": { "get": { "operationId": "listSegmentScheduleTimezones", "tags": [ "Segments" ], "summary": "List schedule timezones", "description": "Returns the timezone choices for a segment owned by the API-key profile.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:read", "parameters": [ { "$ref": "#/components/parameters/SegmentId" }, { "$ref": "#/components/parameters/ProfileIdHeader" } ], "responses": { "200": { "description": "Timezone choices and the profile timezone default.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "timezones", "default", "default_is_valid" ], "properties": { "timezones": { "type": "array", "items": { "type": "string" } }, "default": { "type": "string" }, "default_is_valid": { "type": "boolean", "description": "Whether the profile's configured timezone was in `timezones`; when false, `default` is `UTC`." } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "data": { "timezones": [ "UTC", "America/Los_Angeles" ], "default": "America/Los_Angeles", "default_is_valid": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Segment not found." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/segments/{id}/schedule": { "get": { "operationId": "getSegmentSchedule", "tags": [ "Segments" ], "summary": "Retrieve segment schedule", "description": "Returns `data: null` when the owned segment has no stored clock schedule.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:read", "parameters": [ { "$ref": "#/components/parameters/SegmentId" }, { "$ref": "#/components/parameters/ProfileIdHeader" } ], "responses": { "200": { "description": "The stored clock schedule or null.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": [ "object", "null" ], "additionalProperties": true } } }, "example": { "data": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Segment not found or not owned by this profile." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "saveSegmentSchedule", "tags": [ "Segments" ], "summary": "Set segment schedule", "description": "Saves a clock schedule, sets the segment frequency to `scheduled`, and clears frequency parameters. The segment cannot be negative; `preview_count` is preview-only and rejected here.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:write", "parameters": [ { "$ref": "#/components/parameters/SegmentId" }, { "$ref": "#/components/parameters/ProfileIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentScheduleDefinition" }, "example": { "kind": "cron", "timezone": "America/Los_Angeles", "cron_expression": "0 9 * * 1-5" } } } }, "responses": { "200": { "description": "Saved schedule and occurrences.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "schedule", "occurrences", "max_runs_per_day", "has_nearby_schedule", "nearby_schedule_status" ], "properties": { "schedule": { "type": "object", "additionalProperties": true }, "occurrences": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleOccurrence" } }, "max_runs_per_day": { "type": "integer" }, "has_nearby_schedule": { "type": "boolean" }, "nearby_schedule_status": { "enum": [ "clear", "nearby", "unknown" ] } } } } }, "example": { "data": { "schedule": { "kind": "cron", "timezone": "America/Los_Angeles" }, "occurrences": [ { "utc": "2026-09-01T16:00:00.000Z", "local": "2026-09-01 09:00:00 PDT" } ], "max_runs_per_day": 1, "has_nearby_schedule": false, "nearby_schedule_status": "clear" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Segment not found or not owned by this profile." }, "422": { "description": "Invalid schedule or unsupported negative segment." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteSegmentSchedule", "tags": [ "Segments" ], "summary": "Delete segment schedule", "description": "Removes the schedule and switches the segment to `manual`.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:write", "parameters": [ { "$ref": "#/components/parameters/SegmentId" }, { "$ref": "#/components/parameters/ProfileIdHeader" } ], "responses": { "200": { "description": "Schedule was removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } }, "additionalProperties": false }, "example": { "success": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Segment not found or not owned by this profile." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/segments/{id}/schedule/preview": { "post": { "operationId": "previewSegmentSchedule", "tags": [ "Segments" ], "summary": "Preview segment schedule", "description": "Validates a proposed schedule without saving it for owned non-negative V2 segments.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "segments:write", "parameters": [ { "$ref": "#/components/parameters/SegmentId" }, { "$ref": "#/components/parameters/ProfileIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentSchedulePreviewDefinition" }, "example": { "kind": "once", "timezone": "America/Los_Angeles", "run_once_at": "2026-09-01T16:00:00.000Z", "preview_count": 3 } } } }, "responses": { "200": { "description": "Schedule preview.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "occurrences", "max_runs_per_day", "has_nearby_schedule", "nearby_schedule_status" ], "properties": { "occurrences": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleOccurrence" } }, "max_runs_per_day": { "type": "integer" }, "has_nearby_schedule": { "type": "boolean" }, "nearby_schedule_status": { "enum": [ "clear", "nearby", "unknown" ] } } } } }, "example": { "data": { "occurrences": [ { "utc": "2026-09-01T16:00:00.000Z", "local": "2026-09-01 09:00:00 PDT" } ], "max_runs_per_day": 1, "has_nearby_schedule": false, "nearby_schedule_status": "clear" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Segment not found or not owned by this profile." }, "422": { "description": "Invalid schedule or unsupported negative segment." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/targets": { "get": { "operationId": "listSponsoredProductsTargets", "tags": [ "Targets" ], "summary": "List targets", "description": "Lists Sponsored Products targets for the API-key-authorized `profileid` header. Results come from MerchJar's own target records and carry no performance metrics. Every filter is optional; an unfiltered page returns positive and negative targets of every target type. A successful public target create, update, or archive has already written its local projection before it returned, but a change made in Amazon or another tool appears only after the next MerchJar ingestion.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "targets:read", "parameters": [ { "$ref": "#/components/parameters/ProfileIdHeader" }, { "name": "page", "in": "query", "required": false, "description": "One-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page, from 1 through 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "campaign_id", "in": "query", "required": false, "description": "Return only targets in this campaign. Send the ID as a decimal string.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740994" }, { "name": "ad_group_id", "in": "query", "required": false, "description": "Return only targets in this ad group. Send the ID as a decimal string.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740995" }, { "name": "state", "in": "query", "required": false, "description": "Return only targets in this serving state.", "schema": { "type": "string", "enum": [ "ENABLED", "PAUSED", "ARCHIVED" ] }, "example": "ENABLED" }, { "name": "target_type", "in": "query", "required": false, "description": "Return only targets of this target type, such as `KEYWORD`, `PRODUCT`, `PRODUCT_CATEGORY`, or `THEME`.", "schema": { "type": "string", "minLength": 1 }, "example": "KEYWORD" }, { "name": "negative", "in": "query", "required": false, "description": "Return only negative targets when `true`, or only positive targets when `false`. Omitting this parameter returns both positive and negative targets.", "schema": { "type": "boolean" }, "example": true }, { "name": "sort", "in": "query", "required": false, "description": "Sort field. Prefix with `-` for descending order.", "schema": { "type": "string", "enum": [ "target_id", "-target_id", "last_updated_date_time", "-last_updated_date_time" ], "default": "target_id" }, "example": "-last_updated_date_time" } ], "responses": { "200": { "description": "Paginated targets matching the profile and supplied filters.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One Sponsored Products target, projected from the MerchJar Core target export.", "required": [ "target_id", "profile_id", "campaign_id", "ad_group_id", "ad_product", "target_level", "target_type", "negative", "state", "delivery_status", "delivery_reasons", "bid", "bid_currency_code", "match_type", "keyword", "asin", "created_at", "updated_at" ], "properties": { "target_id": { "allOf": [ { "$ref": "#/components/schemas/BigIntString" } ], "description": "Target ID serialized as a decimal string." }, "profile_id": { "allOf": [ { "$ref": "#/components/schemas/BigIntString" } ], "description": "Profile ID serialized as a decimal string." }, "campaign_id": { "allOf": [ { "$ref": "#/components/schemas/BigIntString" } ], "description": "Campaign ID serialized as a decimal string." }, "ad_group_id": { "anyOf": [ { "$ref": "#/components/schemas/BigIntString" }, { "type": "null" } ], "description": "Ad group ID serialized as a decimal string. A campaign-level target has no ad group and returns null: the stored 0 sentinel is mapped to null, so this field is never \"0\"." }, "ad_product": { "type": "string", "description": "Amazon Advertising product for the target, such as `SPONSORED_PRODUCTS`." }, "target_level": { "type": "string", "description": "Level at which the target is defined, such as `AD_GROUP` or `CAMPAIGN`." }, "target_type": { "type": "string", "description": "Target type, such as `KEYWORD`, `PRODUCT`, `PRODUCT_CATEGORY`, or `THEME`." }, "negative": { "type": "boolean", "description": "True for a negative target. Both polarities are returned unless the `negative` filter is supplied." }, "state": { "type": [ "string", "null" ], "description": "Serving state: `ENABLED`, `PAUSED`, or `ARCHIVED`." }, "delivery_status": { "type": [ "string", "null" ], "description": "Amazon delivery status for the target." }, "delivery_reasons": { "type": [ "array", "null" ], "description": "Amazon delivery reasons for the current delivery status.", "items": { "type": "string" } }, "bid": { "type": [ "integer", "null" ], "description": "Bid in minor currency units, such as 125 for 1.25 USD. Null when the target inherits the ad-group default bid." }, "bid_currency_code": { "type": [ "string", "null" ], "description": "ISO 4217 currency code for `bid`." }, "match_type": { "type": [ "string", "null" ], "description": "Match type for the target expression, such as `EXACT` or `PRODUCT_EXACT`." }, "keyword": { "type": [ "string", "null" ], "description": "Keyword text for a keyword target; null for other target types." }, "asin": { "type": [ "string", "null" ], "description": "Product identifier for a product target; null for other target types." }, "created_at": { "type": [ "string", "null" ], "description": "Target creation timestamp reported by Amazon." }, "updated_at": { "type": [ "string", "null" ], "description": "Target last-update timestamp reported by Amazon." } }, "additionalProperties": false } }, "pagination": { "type": "object", "required": [ "page", "per_page", "total", "last_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "last_page": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "data": [ { "target_id": "9007199254740997", "profile_id": "9007199254740993", "campaign_id": "9007199254740994", "ad_group_id": "9007199254740995", "ad_product": "SPONSORED_PRODUCTS", "target_level": "AD_GROUP", "target_type": "KEYWORD", "negative": false, "state": "ENABLED", "delivery_status": "DELIVERING", "delivery_reasons": [], "bid": 125, "bid_currency_code": "USD", "match_type": "EXACT", "keyword": "running shoes", "asin": null, "created_at": "2026-03-01T12:00:00Z", "updated_at": "2026-03-21T09:30:00Z" } ], "pagination": { "page": 1, "per_page": 25, "total": 1, "last_page": 1 } } } } }, "400": { "description": "The error code is `invalid_parameters` for invalid query parameters or `missing_profile_id` when API-key authentication supplied no profile context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_parameters", "message": "Invalid target list query parameters" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "The target list query failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Failed to read Sponsored Products targets" } } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } }, "post": { "operationId": "createSponsoredProductsTargets", "tags": [ "Target creation" ], "summary": "Create targets", "description": "Creates between 1 and 1,000 Sponsored Products targets for the API-key-authorized `profileid` header. The request schema is strict: unknown fields are rejected before MerchJar calls Amazon. The response is Amazon's raw batch envelope. A `success` or `partialSuccess` result queues local projection; an error-only envelope does not. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This endpoint does not install the standard API-key rate limit middleware, so it does not emit the standard rate limit headers or standard `429` or `503` rate limit responses.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "targets:write", "parameters": [ { "name": "profileid", "in": "header", "required": true, "description": "Positive Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740993" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A batch of Sponsored Products targets to create.", "required": [ "targets" ], "properties": { "targets": { "type": "array", "description": "One to 1,000 targets. Each target uses exactly one target type and matching target-details shape.", "minItems": 1, "maxItems": 1000, "items": { "oneOf": [ { "type": "object", "description": "A keyword target.", "required": [ "adGroupId", "adProduct", "negative", "state", "targetType", "targetDetails" ], "properties": { "adGroupId": { "$ref": "#/components/schemas/BigIntString" }, "adProduct": { "const": "SPONSORED_PRODUCTS", "description": "The Amazon Advertising product for this target." }, "negative": { "const": false, "description": "Public target creation supports positive targets only." }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ], "description": "Initial serving state." }, "targetType": { "const": "KEYWORD", "description": "The target uses a keyword expression." }, "targetDetails": { "type": "object", "description": "Keyword expression details.", "required": [ "keywordTarget" ], "properties": { "keywordTarget": { "type": "object", "description": "The keyword and Amazon match type.", "required": [ "keyword", "matchType" ], "properties": { "keyword": { "type": "string", "minLength": 1, "description": "Keyword text." }, "matchType": { "type": "string", "enum": [ "BROAD", "EXACT", "PHRASE" ], "description": "Amazon keyword match type." } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "description": "A product target using an ASIN or SKU.", "required": [ "adGroupId", "adProduct", "negative", "state", "targetType", "targetDetails" ], "properties": { "adGroupId": { "$ref": "#/components/schemas/BigIntString" }, "adProduct": { "const": "SPONSORED_PRODUCTS", "description": "The Amazon Advertising product for this target." }, "negative": { "const": false, "description": "Public target creation supports positive targets only." }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ], "description": "Initial serving state." }, "targetType": { "const": "PRODUCT", "description": "The target uses a product identifier." }, "targetDetails": { "type": "object", "description": "Product expression details.", "required": [ "productTarget" ], "properties": { "productTarget": { "type": "object", "description": "The product identifier and Amazon product-target match type.", "required": [ "matchType", "productId", "productIdType" ], "properties": { "matchType": { "type": "string", "enum": [ "PRODUCT_COMPLEMENTS", "PRODUCT_EXACT", "PRODUCT_REMARKETING", "PRODUCT_SIMILAR" ], "description": "Amazon product-target match type." }, "productId": { "type": "string", "minLength": 1, "description": "ASIN or SKU to target." }, "productIdType": { "type": "string", "enum": [ "ASIN", "SKU" ], "description": "Identifier type for productId." } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "description": "A product-category target with Amazon category refinements.", "required": [ "adGroupId", "adProduct", "negative", "state", "targetType", "targetDetails" ], "properties": { "adGroupId": { "$ref": "#/components/schemas/BigIntString" }, "adProduct": { "const": "SPONSORED_PRODUCTS", "description": "The Amazon Advertising product for this target." }, "negative": { "const": false, "description": "Public target creation supports positive targets only." }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ], "description": "Initial serving state." }, "targetType": { "const": "PRODUCT_CATEGORY", "description": "The target uses an Amazon product category." }, "targetDetails": { "type": "object", "description": "Product-category expression details.", "required": [ "productCategoryTarget" ], "properties": { "productCategoryTarget": { "type": "object", "description": "Amazon category target and optional refinements.", "required": [ "productCategoryRefinement" ], "properties": { "matchType": { "const": "MULTISIGNAL_BROAD", "description": "Amazon category-target match type when explicitly supplied." }, "productCategoryRefinement": { "type": "object", "description": "Optional filters for the selected category.", "properties": { "productCategoryRefinement": { "type": "object", "description": "Amazon category refinement fields. Omit a field to leave that refinement unconstrained.", "properties": { "productAgeRangeId": { "type": "string", "description": "Amazon age-range identifier." }, "productAgeRangeIdResolved": { "type": "string", "description": "Resolved Amazon age-range identifier." }, "productBrandId": { "type": "string", "description": "Amazon brand identifier." }, "productBrandIdResolved": { "type": "string", "description": "Resolved Amazon brand identifier." }, "productCategoryId": { "type": "string", "description": "Amazon product-category identifier." }, "productCategoryIdResolved": { "type": "string", "description": "Resolved Amazon product-category identifier." }, "productGenreId": { "type": "string", "description": "Amazon product-genre identifier." }, "productPriceGreaterThan": { "type": "number", "description": "Lower product-price bound." }, "productPriceLessThan": { "type": "number", "description": "Upper product-price bound." }, "productPrimeShippingEligible": { "type": "boolean", "description": "Whether to require Prime-eligible products." }, "productRatingGreaterThan": { "type": "number", "description": "Lower product-rating bound." }, "productRatingLessThan": { "type": "number", "description": "Upper product-rating bound." } }, "additionalProperties": false } }, "additionalProperties": false }, "productGenreRefinement": { "type": "object", "description": "Optional Amazon product-genre filter.", "required": [ "productGenreId" ], "properties": { "productGenreId": { "type": "string", "description": "Amazon product-genre identifier." } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "description": "An Amazon theme target, formerly known as an automatic target for Sponsored Products.", "required": [ "adGroupId", "adProduct", "negative", "state", "targetType", "targetDetails" ], "properties": { "adGroupId": { "$ref": "#/components/schemas/BigIntString" }, "adProduct": { "const": "SPONSORED_PRODUCTS", "description": "The Amazon Advertising product for this target." }, "negative": { "const": false, "description": "Public target creation supports positive targets only." }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ], "description": "Initial serving state." }, "targetType": { "const": "THEME", "description": "The target uses an Amazon theme; AUTO is not a target type." }, "targetDetails": { "type": "object", "description": "Theme expression details.", "required": [ "themeTarget" ], "properties": { "themeTarget": { "type": "object", "description": "The Amazon theme match type.", "required": [ "matchType" ], "properties": { "matchType": { "type": "string", "enum": [ "INTERESTED_AUDIENCE", "KEYWORDS_CLOSE_MATCH", "KEYWORDS_LOOSE_MATCH", "KEYWORDS_RELATED_TO_GIFTS", "KEYWORDS_RELATED_TO_PEER_BRANDS_PRODUCT_CATEGORY", "KEYWORDS_RELATED_TO_PRIME_DAY", "KEYWORDS_RELATED_TO_YOUR_BRAND", "KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES", "KEYWORDS_RELATED_TO_YOUR_PRODUCT_CATEGORY", "PRODUCTS_SIMILAR_TO_ADVERTISED_PRODUCTS", "PRODUCT_COMPLEMENTS", "PRODUCT_SUBSTITUTES" ], "description": "Amazon theme-target match type." } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "description": "A negative ad-group-level keyword target.", "required": [ "adGroupId", "adProduct", "negative", "state", "targetType", "targetDetails" ], "properties": { "adGroupId": { "$ref": "#/components/schemas/BigIntString" }, "adProduct": { "const": "SPONSORED_PRODUCTS" }, "negative": { "const": true }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ] }, "targetType": { "const": "KEYWORD" }, "targetDetails": { "type": "object", "required": [ "keywordTarget" ], "properties": { "keywordTarget": { "type": "object", "required": [ "keyword", "matchType" ], "properties": { "keyword": { "type": "string", "minLength": 1 }, "matchType": { "type": "string", "enum": [ "BROAD", "EXACT", "PHRASE" ] } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "description": "A negative campaign-level keyword target.", "required": [ "campaignId", "adProduct", "negative", "state", "targetType", "targetDetails" ], "properties": { "campaignId": { "$ref": "#/components/schemas/BigIntString" }, "adProduct": { "const": "SPONSORED_PRODUCTS" }, "negative": { "const": true }, "state": { "type": "string", "enum": [ "ENABLED", "PAUSED" ] }, "targetType": { "const": "KEYWORD" }, "targetDetails": { "type": "object", "required": [ "keywordTarget" ], "properties": { "keywordTarget": { "type": "object", "required": [ "keyword", "matchType" ], "properties": { "keyword": { "type": "string", "minLength": 1 }, "matchType": { "type": "string", "enum": [ "BROAD", "EXACT", "PHRASE" ] } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } ] } } }, "additionalProperties": false }, "examples": { "productTarget": { "summary": "Create one product target", "value": { "targets": [ { "adGroupId": "9007199254740995", "adProduct": "SPONSORED_PRODUCTS", "negative": false, "state": "ENABLED", "targetType": "PRODUCT", "targetDetails": { "productTarget": { "matchType": "PRODUCT_EXACT", "productId": "B012345678", "productIdType": "ASIN" } } } ] } } } } } }, "responses": { "200": { "description": "Amazon's raw batch-create envelope. At least one non-empty `success`, `partialSuccess`, or `error` array is present. Result-item fields are controlled by Amazon and may evolve.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmazonBatchCreateEnvelope" }, "examples": { "success": { "summary": "Amazon accepted the target", "value": { "success": [ { "index": 0, "target": { "targetId": "9007199254740997" } } ] } } } } } }, "400": { "description": "Invalid JSON or an invalid strict target-create request, profile ID, or profile context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Invalid Sponsored Products target create request" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Amazon transport failed or returned no recognised result array. Target creation may have reached Amazon; check Amazon before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "public_create_outcome_unknown", "message": "Target creation outcome is unknown; check Amazon before retrying" } } } } } } } }, "/targets/{id}": { "get": { "operationId": "retrieveSponsoredProductsTarget", "tags": [ "Targets" ], "summary": "Retrieve a target", "description": "Retrieves one Sponsored Products target owned by the API-key-authorized `profileid` header. The response carries no performance metrics. A target belonging to another profile is reported as `404 not_found`, so a cross-profile ID is indistinguishable from an absent ID.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "targets:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Target ID. Send it as a positive decimal string, never as a JavaScript number.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740997" }, { "$ref": "#/components/parameters/ProfileIdHeader" } ], "responses": { "200": { "description": "The requested target.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "One Sponsored Products target, projected from the MerchJar Core target export.", "required": [ "target_id", "profile_id", "campaign_id", "ad_group_id", "ad_product", "target_level", "target_type", "negative", "state", "delivery_status", "delivery_reasons", "bid", "bid_currency_code", "match_type", "keyword", "asin", "created_at", "updated_at" ], "properties": { "target_id": { "allOf": [ { "$ref": "#/components/schemas/BigIntString" } ], "description": "Target ID serialized as a decimal string." }, "profile_id": { "allOf": [ { "$ref": "#/components/schemas/BigIntString" } ], "description": "Profile ID serialized as a decimal string." }, "campaign_id": { "allOf": [ { "$ref": "#/components/schemas/BigIntString" } ], "description": "Campaign ID serialized as a decimal string." }, "ad_group_id": { "anyOf": [ { "$ref": "#/components/schemas/BigIntString" }, { "type": "null" } ], "description": "Ad group ID serialized as a decimal string. A campaign-level target has no ad group and returns null: the stored 0 sentinel is mapped to null, so this field is never \"0\"." }, "ad_product": { "type": "string", "description": "Amazon Advertising product for the target, such as `SPONSORED_PRODUCTS`." }, "target_level": { "type": "string", "description": "Level at which the target is defined, such as `AD_GROUP` or `CAMPAIGN`." }, "target_type": { "type": "string", "description": "Target type, such as `KEYWORD`, `PRODUCT`, `PRODUCT_CATEGORY`, or `THEME`." }, "negative": { "type": "boolean", "description": "True for a negative target. Both polarities are returned unless the `negative` filter is supplied." }, "state": { "type": [ "string", "null" ], "description": "Serving state: `ENABLED`, `PAUSED`, or `ARCHIVED`." }, "delivery_status": { "type": [ "string", "null" ], "description": "Amazon delivery status for the target." }, "delivery_reasons": { "type": [ "array", "null" ], "description": "Amazon delivery reasons for the current delivery status.", "items": { "type": "string" } }, "bid": { "type": [ "integer", "null" ], "description": "Bid in minor currency units, such as 125 for 1.25 USD. Null when the target inherits the ad-group default bid." }, "bid_currency_code": { "type": [ "string", "null" ], "description": "ISO 4217 currency code for `bid`." }, "match_type": { "type": [ "string", "null" ], "description": "Match type for the target expression, such as `EXACT` or `PRODUCT_EXACT`." }, "keyword": { "type": [ "string", "null" ], "description": "Keyword text for a keyword target; null for other target types." }, "asin": { "type": [ "string", "null" ], "description": "Product identifier for a product target; null for other target types." }, "created_at": { "type": [ "string", "null" ], "description": "Target creation timestamp reported by Amazon." }, "updated_at": { "type": [ "string", "null" ], "description": "Target last-update timestamp reported by Amazon." } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "data": { "target_id": "9007199254740997", "profile_id": "9007199254740993", "campaign_id": "9007199254740994", "ad_group_id": "9007199254740995", "ad_product": "SPONSORED_PRODUCTS", "target_level": "AD_GROUP", "target_type": "KEYWORD", "negative": false, "state": "ENABLED", "delivery_status": "DELIVERING", "delivery_reasons": [], "bid": 125, "bid_currency_code": "USD", "match_type": "EXACT", "keyword": "running shoes", "asin": null, "created_at": "2026-03-01T12:00:00Z", "updated_at": "2026-03-21T09:30:00Z" } } } } }, "400": { "description": "The error code is `invalid_target_id` for an invalid path ID or `missing_profile_id` when API-key authentication supplied no profile context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_target_id", "message": "Target ID must be a positive decimal string" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No target with this ID belongs to the profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Target not found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "The target detail query failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Failed to read Sponsored Products targets" } } } } }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } }, "patch": { "operationId": "updateSponsoredProductsTarget", "tags": [ "Target creation" ], "summary": "Update a target", "description": "Updates only `bid` and/or `state` for one Sponsored Products target. An `Idempotency-Key` is required.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "targets:write", "parameters": [ { "name": "id", "in": "path", "required": true, "example": "9007199254740995", "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "profileid", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bid": { "type": "object", "required": [ "bid" ], "properties": { "bid": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "state": { "enum": [ "ENABLED", "PAUSED" ] } }, "anyOf": [ { "required": [ "bid" ] }, { "required": [ "state" ] } ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Amazon raw update envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Target not found" }, "502": { "description": "Outcome unknown; verify Amazon before retrying" } } }, "delete": { "operationId": "archiveSponsoredProductsTarget", "tags": [ "Target creation" ], "summary": "Delete a target", "description": "Archives one Sponsored Products target and confirms Amazon reports `ARCHIVED` before local projection. An Idempotency-Key is required.", "security": [ { "API-Key": [] } ], "x-merchjar-required-scope": "targets:archive", "parameters": [ { "name": "id", "in": "path", "required": true, "example": "9007199254740995", "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "profileid", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Amazon raw delete envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Target not found" }, "409": { "description": "Target is already archived" }, "502": { "description": "Outcome unknown; verify Amazon before retrying" } } } } }, "components": { "securitySchemes": { "API-Key": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Pass a MerchJar API key in the Authorization header: `Bearer mj_live_…`. Each operation declares its required key scope with `x-merchjar-required-scope`." } }, "schemas": { "BigIntString": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.", "example": "9007199254740993" }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable error code." }, "message": { "type": "string", "description": "A human-readable explanation of the error." } }, "additionalProperties": true }, "ErrorEnvelope": { "type": "object", "description": "The JSON error envelope returned by handled MerchJar API failures.", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "additionalProperties": false }, "AmazonBatchCreateEnvelope": { "type": "object", "description": "An Amazon batch-create result. MerchJar preserves result-item fields from Amazon, so their shape can evolve. The `success`, `partialSuccess`, and `error` arrays are each optional, may appear together, and are not ordered. A result item's integer `index` identifies the item at that zero-based position in the original request array. At least one result array is non-empty.", "properties": { "success": { "type": "array", "description": "Items Amazon created successfully. Each item's `index`, when present, maps to the original request item.", "items": { "type": "object", "description": "An Amazon success result item whose fields are passed through unchanged.", "additionalProperties": true } }, "partialSuccess": { "type": "array", "description": "Items Amazon created with partial-success details. Each item's `index`, when present, maps to the original request item.", "items": { "type": "object", "description": "An Amazon partial-success result item whose fields are passed through unchanged.", "additionalProperties": true } }, "error": { "type": "array", "description": "Items Amazon rejected. Each item's `index`, when present, maps to the original request item.", "items": { "type": "object", "description": "An Amazon error result item whose fields are passed through unchanged.", "additionalProperties": true } } }, "anyOf": [ { "required": [ "success" ], "properties": { "success": { "minItems": 1 } } }, { "required": [ "partialSuccess" ], "properties": { "partialSuccess": { "minItems": 1 } } }, { "required": [ "error" ], "properties": { "error": { "minItems": 1 } } } ], "additionalProperties": true }, "BulkActionJob": { "type": "object", "required": [ "request_id", "profile_id", "entity_type", "action", "status", "reason_code", "counts", "created_at", "started_at", "completed_at" ], "properties": { "request_id": { "type": "string", "maxLength": 64 }, "profile_id": { "$ref": "#/components/schemas/BigIntString" }, "entity_type": { "type": "string", "enum": [ "campaigns", "ad_groups", "keywords", "targets", "product_ads", "negative_keywords", "negative_targets", "campaign_negative_keywords" ] }, "action": { "oneOf": [ { "$ref": "#/components/schemas/BulkActionSetState" }, { "$ref": "#/components/schemas/BulkActionSetDailyBudget" }, { "$ref": "#/components/schemas/BulkActionAdjustDailyBudget" }, { "$ref": "#/components/schemas/BulkActionSetBid" }, { "$ref": "#/components/schemas/BulkActionAdjustBid" }, { "$ref": "#/components/schemas/BulkActionSetDefaultBid" } ], "discriminator": { "propertyName": "type" } }, "status": { "type": "string", "enum": [ "queued", "running", "complete", "partial", "failed", "dead_lettered" ] }, "reason_code": { "type": [ "string", "null" ], "description": "Terminal failure reason when available, such as `attempts_exhausted` or `out_of_sync`." }, "counts": { "type": [ "object", "null" ], "description": "Null while queued or running.", "required": [ "requested", "succeeded", "failed", "unchanged", "skipped_archived", "skipped_invalid" ], "properties": { "requested": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "unchanged": { "type": "integer", "minimum": 0 }, "skipped_archived": { "type": "integer", "minimum": 0 }, "skipped_invalid": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "items": { "type": "array", "description": "Present only for terminal responses, as the requested page of item outcomes.", "items": { "type": "object", "required": [ "entity_id", "status" ], "properties": { "entity_id": { "$ref": "#/components/schemas/BigIntString" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "unchanged", "skipped" ] }, "reason": { "type": "string", "enum": [ "archived", "invalid" ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "BulkActionAcceptedResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BulkActionJob" } }, "additionalProperties": false }, "BulkActionTerminalResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "$ref": "#/components/schemas/BulkActionJob" }, "pagination": { "$ref": "#/components/schemas/BulkActionPagination" } }, "additionalProperties": false }, "BulkActionPagination": { "type": "object", "required": [ "page", "per_page", "total", "last_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 1000 }, "total": { "type": "integer", "minimum": 0 }, "last_page": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "BulkActionSetState": { "type": "object", "required": [ "type", "state" ], "properties": { "type": { "const": "set_state" }, "state": { "type": "string", "enum": [ "enabled", "paused", "archived" ] } }, "additionalProperties": false }, "BulkActionSetDailyBudget": { "type": "object", "example": { "type": "set_daily_budget", "amount": 12.34 }, "required": [ "type", "amount" ], "properties": { "type": { "const": "set_daily_budget" }, "amount": { "type": "number", "exclusiveMinimum": 0, "multipleOf": 0.01 } }, "additionalProperties": false }, "BulkActionAdjustDailyBudget": { "type": "object", "example": { "type": "adjust_daily_budget", "percent": -10 }, "required": [ "type", "percent" ], "properties": { "type": { "const": "adjust_daily_budget" }, "percent": { "type": "number", "minimum": -99, "maximum": 1000, "not": { "const": 0 } } }, "additionalProperties": false }, "BulkActionSetBid": { "type": "object", "example": { "type": "set_bid", "amount": 0.75 }, "required": [ "type", "amount" ], "properties": { "type": { "const": "set_bid" }, "amount": { "type": "number", "exclusiveMinimum": 0, "multipleOf": 0.01 } }, "additionalProperties": false }, "BulkActionAdjustBid": { "type": "object", "example": { "type": "adjust_bid", "percent": 10 }, "required": [ "type", "percent" ], "properties": { "type": { "const": "adjust_bid" }, "percent": { "type": "number", "minimum": -99, "maximum": 1000, "not": { "const": 0 } } }, "additionalProperties": false }, "BulkActionSetDefaultBid": { "type": "object", "example": { "type": "set_default_bid", "amount": 0.75 }, "required": [ "type", "amount" ], "properties": { "type": { "const": "set_default_bid" }, "amount": { "type": "number", "exclusiveMinimum": 0, "multipleOf": 0.01 } }, "additionalProperties": false }, "CustomFieldEntityType": { "type": "string", "enum": [ "campaign", "ad_group", "target", "ad" ], "example": "campaign" }, "CustomFieldDefinitionCreate": { "type": "object", "required": [ "entity_type", "name", "data_type" ], "properties": { "entity_type": { "$ref": "#/components/schemas/CustomFieldEntityType" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "data_type": { "type": "integer", "enum": [ 1, 2, 3 ] } }, "additionalProperties": false }, "CustomFieldDefinitionUpdate": { "type": "object", "required": [ "entity_type", "expected_version", "name" ], "properties": { "entity_type": { "$ref": "#/components/schemas/CustomFieldEntityType" }, "expected_version": { "$ref": "#/components/schemas/BigIntString" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CustomFieldDefinitionDelete": { "type": "object", "required": [ "entity_type", "expected_version" ], "properties": { "entity_type": { "$ref": "#/components/schemas/CustomFieldEntityType" }, "expected_version": { "$ref": "#/components/schemas/BigIntString" }, "disable_dependants": { "type": "boolean" } }, "additionalProperties": false }, "CustomFieldBulkMutation": { "type": "object", "required": [ "mutations" ], "properties": { "mutations": { "type": "array", "items": { "type": "object", "required": [ "field_definition_id", "entity_id", "operation" ], "properties": { "field_definition_id": { "$ref": "#/components/schemas/BigIntString" }, "entity_id": { "$ref": "#/components/schemas/BigIntString" }, "operation": { "enum": [ "set", "clear" ] }, "value": { "type": [ "string", "boolean" ] }, "expected_version": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*$" } } } }, "source_reference": { "type": [ "string", "null" ], "maxLength": 100 } } }, "SegmentScheduleDefinition": { "oneOf": [ { "type": "object", "required": [ "kind", "timezone", "cron_expression" ], "properties": { "kind": { "const": "cron" }, "timezone": { "type": "string" }, "cron_expression": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "timezone", "run_once_at" ], "properties": { "kind": { "const": "once" }, "timezone": { "type": "string" }, "run_once_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } ] }, "SegmentSchedulePreviewDefinition": { "description": "A proposed clock schedule. `preview_count` is accepted only by the preview endpoint and is not a persistable schedule field.", "oneOf": [ { "type": "object", "required": [ "kind", "timezone", "cron_expression" ], "properties": { "kind": { "const": "cron" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "cron_expression": { "type": "string", "minLength": 1, "maxLength": 128 }, "run_once_at": { "type": "null" }, "preview_count": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "timezone", "run_once_at" ], "properties": { "kind": { "const": "once" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "cron_expression": { "type": "null" }, "run_once_at": { "type": "string", "format": "date-time", "minLength": 1 }, "preview_count": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 } }, "additionalProperties": false } ] }, "ScheduleOccurrence": { "type": "object", "required": [ "utc", "local" ], "properties": { "utc": { "type": "string", "format": "date-time", "description": "Occurrence in UTC." }, "local": { "type": "string", "description": "Occurrence rendered in the schedule timezone." } }, "additionalProperties": false } }, "parameters": { "ProfileIdHeader": { "name": "profileid", "in": "header", "required": true, "description": "Positive decimal Amazon Advertising profile ID owned by the API-key user.", "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740993" }, "CustomFieldEntityType": { "name": "entityType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CustomFieldEntityType" }, "example": "campaign" }, "CustomFieldJobId": { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "job_01HXYZ" }, "CustomFieldDefinitionId": { "name": "definitionId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "1" }, "SegmentId": { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BigIntString" }, "example": "9007199254740997" } }, "headers": { "XRateLimitLimit": { "description": "Maximum requests permitted for this API key during the current 60-second window.", "schema": { "type": "integer", "minimum": 1 }, "example": 1200 }, "XRateLimitRemaining": { "description": "Requests remaining for this API key during the current 60-second window.", "schema": { "type": "integer", "minimum": 0 }, "example": 1199 }, "XRateLimitReset": { "description": "Unix timestamp in seconds when the current rate limit window resets.", "schema": { "type": "integer", "minimum": 0 }, "example": 1742400042 }, "RetryAfter": { "description": "Seconds to wait before retrying a rate limited or temporarily unavailable request.", "schema": { "type": "integer", "minimum": 1 }, "example": 42 } }, "responses": { "CustomFieldData": { "description": "Custom-field response data.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "values": [] } } } }, "CustomFieldDefinition": { "description": "A custom-field definition.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "definition": { "id": "1", "name": "Priority" } } } } }, "CustomFieldJob": { "description": "A custom-field CSV job.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "job": { "id": "job_01HXYZ", "status": "queued" } } } } }, "CustomFieldJobAccepted": { "description": "A custom-field CSV job was queued.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "job": { "id": "job_01HXYZ", "status": "queued" } } } } }, "BadRequest": { "description": "The request is malformed or contains an invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "The API key lacks the required scope or access to the requested profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "The API key has exceeded its rate limit.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimitUnavailable": { "description": "Rate limit admission is temporarily unavailable; retry after the supplied delay. The error code is `rate_limit_unavailable`.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InternalServerError": { "description": "An unexpected server error occurred.", "content": { "text/plain": { "schema": { "type": "string", "example": "Internal Server Error" } } } } } } }