{"openapi":"3.0.0","paths":{"/health":{"get":{"operationId":"HealthController_health","parameters":[],"responses":{"200":{"description":""}},"tags":["Health"]}},"/v1/me":{"get":{"summary":"Describe the authenticated credential (API key or OAuth grant): scopes and accessible accounts","tags":["me"],"parameters":[{"name":"include_onboarding","in":"query","description":"Set to `true` to add `onboarding` to every account: the onboarding steps done and pending, the next one, whether the first data download finished and the link to connect channels.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["api_key","oauth_token"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"subject_type":{"type":"string","enum":["business","agency"]},"scopes":{"type":"array","items":{"type":"string","enum":["catalog:read","catalog:write","campaigns:read","campaigns:write","connections:read","tasks:read","tasks:write","skills:read","workflows:read","workflows:write","platform:read","platform:write","costs:write","catalog:publish"]}},"account_required":{"type":"boolean"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"nullable":true,"type":"string"},"onboarding":{"type":"object","properties":{"steps":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["connect_channel","connect_advertising","connect_ai","create_brand","add_competitors","create_cluster","create_prompt","add_product_costs","optimize_listings","publish_listing_changes","clone_workflow_template","activate_workflow","first_workflow_run","enable_stock_forecast","create_manual_task","create_view","try_velax"]},"done":{"type":"boolean"},"completed_at":{"nullable":true,"type":"string"},"skipped":{"type":"boolean"}},"required":["key","done","completed_at","skipped"],"additionalProperties":false}},"next_step":{"nullable":true,"type":"string","enum":["connect_channel","connect_advertising","connect_ai","create_brand","add_competitors","create_cluster","create_prompt","add_product_costs","optimize_listings","publish_listing_changes","clone_workflow_template","activate_workflow","first_workflow_run","enable_stock_forecast","create_manual_task","create_view","try_velax"]},"initial_sync_completed":{"type":"boolean"},"ads_initial_sync_completed":{"type":"boolean"},"connections_url":{"type":"string"}},"required":["steps","next_step","initial_sync_completed","ads_initial_sync_completed","connections_url"],"additionalProperties":false}},"required":["id","name"],"additionalProperties":false}}},"required":["object","id","subject_type","scopes","account_required","accounts"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/onboarding/steps/{key}":{"patch":{"summary":"Skip an onboarding step of the account, or take it up again","tags":["onboarding"],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","enum":["connect_channel","connect_advertising","create_brand","add_competitors","create_cluster","create_prompt","add_product_costs","optimize_listings","publish_listing_changes","clone_workflow_template","activate_workflow","first_workflow_run"]}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"skipped":{"type":"boolean","description":"`true` when the person says they skip this step (for `connect_advertising`: they do not want Amazon Ads); `false` to take it up again."}},"required":["skipped"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"steps":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["connect_channel","connect_advertising","connect_ai","create_brand","add_competitors","create_cluster","create_prompt","add_product_costs","optimize_listings","publish_listing_changes","clone_workflow_template","activate_workflow","first_workflow_run","enable_stock_forecast","create_manual_task","create_view","try_velax"]},"done":{"type":"boolean"},"completed_at":{"nullable":true,"type":"string"},"skipped":{"type":"boolean"}},"required":["key","done","completed_at","skipped"],"additionalProperties":false}},"next_step":{"nullable":true,"type":"string","enum":["connect_channel","connect_advertising","connect_ai","create_brand","add_competitors","create_cluster","create_prompt","add_product_costs","optimize_listings","publish_listing_changes","clone_workflow_template","activate_workflow","first_workflow_run","enable_stock_forecast","create_manual_task","create_view","try_velax"]},"initial_sync_completed":{"type":"boolean"},"ads_initial_sync_completed":{"type":"boolean"},"connections_url":{"type":"string"}},"required":["steps","next_step","initial_sync_completed","ads_initial_sync_completed","connections_url"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/accounts":{"get":{"summary":"List the accounts this API key can operate on","tags":["accounts"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["account"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"nullable":true,"type":"string"},"connections":{"nullable":true,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["object","id","name","connections"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/connections":{"get":{"summary":"List the authenticated account's connections","tags":["connections"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the connection name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/connections/{id}":{"get":{"tags":["connections"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/connections/{id}/sync-runs":{"get":{"summary":"List the sync runs of a connection, newest first","tags":["connections"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"How many runs to return, newest first (1 to 31, default 1). Each run is billed as one row.","schema":{"default":1,"type":"integer","minimum":1,"maximum":31}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["sync_run"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"trigger":{"type":"string","enum":["manual","scheduled","admin","api","initial"]},"status":{"type":"string","enum":["in_progress","completed","completed_with_errors","failed","cancelled"]},"reason_code":{"nullable":true,"type":"string","enum":["amazon_fatal","amazon_cancelled","retries_exhausted","no_document","no_vendor_codes","no_marketplaces","deadline","superseded","merchant_not_recorded","internal_error"]},"started_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"finished_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deadline_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"milestones":{"type":"object","properties":{"catalog_done_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"amazon_ready_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"readable_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["catalog_done_at","amazon_ready_at","readable_at"],"additionalProperties":false},"parts":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["catalog","orders","salesTraffic","economics","vendorAnalytics","clickhouse","afnInventory","adsMetadata","adsExports","spReports","sbReports","sdReports"]},"scope":{"type":"string","enum":["market","account"]},"informative":{"type":"boolean"},"state":{"type":"string","enum":["pending","ready","not_ready"]},"has_errors":{"type":"boolean"}},"required":["key","scope","informative","state","has_errors"],"additionalProperties":false}},"markets":{"type":"array","items":{"type":"object","properties":{"country_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"catalog":{"nullable":true,"type":"object","properties":{"status":{"type":"string","enum":["pending","data","empty","failed","expired"]},"reason_code":{"nullable":true,"type":"string","enum":["amazon_fatal","amazon_cancelled","retries_exhausted","no_document","no_vendor_codes","no_marketplaces","deadline","superseded","merchant_not_recorded","internal_error"]},"finished_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["status","reason_code","finished_at"],"additionalProperties":false},"rows":{"type":"object","properties":{"orders":{"type":"number"},"sales_traffic":{"type":"number"},"economics":{"type":"number"},"vendor_analytics":{"type":"number"}},"required":["orders","sales_traffic","economics","vendor_analytics"],"additionalProperties":false}},"required":["country_id","code","catalog","rows"],"additionalProperties":false}},"account_parts":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["orders","salesTraffic","economics","vendorAnalytics","clickhouse","afnInventory","adsMetadata","adsExports","spReports","sbReports","sdReports"]},"expected":{"nullable":true,"type":"number"},"data":{"type":"number"},"empty":{"type":"number"},"failed":{"type":"number"},"expired":{"type":"number"},"finished_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"failures":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"status":{"type":"string","enum":["failed","expired"]},"reason_code":{"nullable":true,"type":"string","enum":["amazon_fatal","amazon_cancelled","retries_exhausted","no_document","no_vendor_codes","no_marketplaces","deadline","superseded","merchant_not_recorded","internal_error"]}},"required":["label","status","reason_code"],"additionalProperties":false}}},"required":["key","expected","data","empty","failed","expired","finished_at","failures"],"additionalProperties":false}},"product_details":{"nullable":true,"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"markets":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"status":{"nullable":true,"type":"string","enum":["idle","in-progress","completed","stuck"]},"last_completed_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["code","status","last_completed_at"],"additionalProperties":false}}},"required":["endpoint","markets"],"additionalProperties":false}}},"required":["object","id","connection_id","trigger","status","reason_code","started_at","finished_at","deadline_at","milestones","parts","markets","account_parts","product_details"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/countries":{"get":{"summary":"List Amazon marketplace countries","tags":["countries"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"code","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/countries/{id}":{"get":{"tags":["countries"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/currencies/convert":{"get":{"summary":"Convert an amount between currencies with the daily exchange rate","tags":["currencies"],"parameters":[{"name":"amount","in":"query","description":"Amount to convert, in `from`.","required":true,"schema":{"type":"number","minimum":0}},{"name":"from","in":"query","description":"ISO 4217 code, e.g. `EUR`, `PLN`, `GBP`, `USD`, `SEK`. Case-insensitive.","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"to","in":"query","description":"ISO 4217 code, e.g. `EUR`, `PLN`, `GBP`, `USD`, `SEK`. Case-insensitive.","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["currency_conversion"]},"amount":{"type":"number"},"from":{"type":"string"},"to":{"type":"string"},"rate":{"type":"number","description":"Units of `to` per 1 `from`, unrounded."},"converted":{"type":"number","description":"`amount` in `to`, rounded to 2 decimals (the precision of an Amazon price). Do not round it again."},"rate_date":{"type":"string","description":"When the rate was last refreshed (ISO 8601). Tell the user the rate and this date when you use the result."}},"required":["object","amount","from","to","rate","converted","rate_date"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-brands":{"get":{"summary":"List the brands present in the authenticated account's catalog","tags":["product-brands"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the brand name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-brands/{id}":{"get":{"tags":["product-brands"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/products":{"get":{"summary":"List the authenticated account's products","tags":["products"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the product title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"brand","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}},{"name":"cost_state","in":"query","description":"Only active catalog products `with` a cost, `missing` one, or `missing_with_sales`: no cost and sales in the last 30 days, the ones that inflate the margin. Those sales are calculated every night, so on an account connected in the last few days it can come back empty while products have no cost: then use `missing`, and `coverage` in the P&L for how much of the sales lacks a cost. Combine with `include_total` for counts. Business and Master plans only.","schema":{"type":"string","enum":["with","missing","missing_with_sales"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"cost":{"nullable":true,"description":"Product and shipping cost in force today, the same that feeds the P&L. `null` for advertising products and on plans without product cost (Free and Guru).","type":"object","properties":{"cogs":{"nullable":true,"description":"Unit cost of the product in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false},"shipping":{"nullable":true,"description":"Unit shipping cost in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false}},"required":["cogs","shipping"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","cost","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/products/{id}":{"get":{"tags":["products"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"cost":{"nullable":true,"description":"Product and shipping cost in force today, the same that feeds the P&L. `null` for advertising products and on plans without product cost (Free and Guru).","type":"object","properties":{"cogs":{"nullable":true,"description":"Unit cost of the product in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false},"shipping":{"nullable":true,"description":"Unit shipping cost in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false}},"required":["cogs","shipping"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","cost","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-seller-products":{"get":{"summary":"List the authenticated account's Amazon seller products","tags":["amazon-seller-products"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"blocked","in":"query","description":"`true` returns only listings Amazon is blocking, `false` only the ones it is not. Listings not synced yet match neither.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"brand","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"blocked":{"nullable":true,"description":"Whether Amazon is blocking the sale of this listing: the catalog item was removed or the offer suppressed. Updated on every listing sync (at most a day behind Amazon). `null` when the listing has not been synced yet. The reason is in the listing issues (`expand[]=sellerCentralInfo` or `expand[]=vendorCentralInfo`).","type":"boolean"},"sellerCentralInfo":{},"catalogPublicInfo":{},"pricing":{},"buyboxB2C":{},"buyboxB2B":{},"fbaInventory":{},"aplusContent":{},"competitivePriceSummary":{},"suppressed":{},"fbaLocalStock":{},"salesRanks":{},"amazonStatus":{"nullable":true,"type":"string"},"publicParentSKU":{"nullable":true,"type":"string"},"publicParentASIN":{"nullable":true,"type":"string"},"publicIsParentASIN":{"nullable":true,"type":"boolean"},"backendParentSKU":{"nullable":true,"type":"string"},"backendParentASIN":{"nullable":true,"type":"string"},"backendIsParentASIN":{"nullable":true,"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","blocked","amazonStatus","publicParentSKU","publicParentASIN","publicIsParentASIN","backendParentSKU","backendParentASIN","backendIsParentASIN","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-seller-products/{id}":{"get":{"tags":["amazon-seller-products"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"blocked":{"nullable":true,"description":"Whether Amazon is blocking the sale of this listing: the catalog item was removed or the offer suppressed. Updated on every listing sync (at most a day behind Amazon). `null` when the listing has not been synced yet. The reason is in the listing issues (`expand[]=sellerCentralInfo` or `expand[]=vendorCentralInfo`).","type":"boolean"},"sellerCentralInfo":{},"catalogPublicInfo":{},"pricing":{},"buyboxB2C":{},"buyboxB2B":{},"fbaInventory":{},"aplusContent":{},"competitivePriceSummary":{},"suppressed":{},"fbaLocalStock":{},"salesRanks":{},"amazonStatus":{"nullable":true,"type":"string"},"publicParentSKU":{"nullable":true,"type":"string"},"publicParentASIN":{"nullable":true,"type":"string"},"publicIsParentASIN":{"nullable":true,"type":"boolean"},"backendParentSKU":{"nullable":true,"type":"string"},"backendParentASIN":{"nullable":true,"type":"string"},"backendIsParentASIN":{"nullable":true,"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","blocked","amazonStatus","publicParentSKU","publicParentASIN","publicIsParentASIN","backendParentSKU","backendParentASIN","backendIsParentASIN","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-vendor-products":{"get":{"summary":"List the authenticated account's Amazon vendor products","tags":["amazon-vendor-products"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"blocked","in":"query","description":"`true` returns only listings Amazon is blocking, `false` only the ones it is not. Listings not synced yet match neither.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"brand","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"blocked":{"nullable":true,"description":"Whether Amazon is blocking the sale of this listing: the catalog item was removed or the offer suppressed. Updated on every listing sync (at most a day behind Amazon). `null` when the listing has not been synced yet. The reason is in the listing issues (`expand[]=sellerCentralInfo` or `expand[]=vendorCentralInfo`).","type":"boolean"},"vendorCentralInfo":{},"catalogPublicInfo":{},"aplusContent":{},"inventory":{},"salesRanks":{},"customerFeedback":{},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","blocked","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-vendor-products/{id}":{"get":{"tags":["amazon-vendor-products"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"blocked":{"nullable":true,"description":"Whether Amazon is blocking the sale of this listing: the catalog item was removed or the offer suppressed. Updated on every listing sync (at most a day behind Amazon). `null` when the listing has not been synced yet. The reason is in the listing issues (`expand[]=sellerCentralInfo` or `expand[]=vendorCentralInfo`).","type":"boolean"},"vendorCentralInfo":{},"catalogPublicInfo":{},"aplusContent":{},"inventory":{},"salesRanks":{},"customerFeedback":{},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","blocked","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-advertising-products":{"get":{"summary":"List the authenticated account's Amazon advertising products","tags":["amazon-advertising-products"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the listing title, ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"brand","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"availability":{"nullable":true,"type":"string","enum":["IN_STOCK","IN_STOCK_SCARCE","OUT_OF_STOCK","PREORDER","LEADTIME","AVAILABLE_DATE"]},"eligibilityStatus":{"nullable":true,"type":"string","enum":["ELIGIBLE","INELIGIBLE"]},"ineligibilityCodes":{"type":"array","items":{"type":"string"}},"ineligibilityReasons":{"type":"array","items":{"type":"string"}},"basisPrice":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"],"additionalProperties":false},"bestSellerRank":{"nullable":true,"type":"string"},"firstAvailabilityDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"categoryName":{"nullable":true,"type":"string"},"brandName":{"nullable":true,"type":"string"},"variationList":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","availability","eligibilityStatus","ineligibilityCodes","ineligibilityReasons","basisPrice","bestSellerRank","firstAvailabilityDate","categoryName","brandName","variationList","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-advertising-products/{id}":{"get":{"tags":["amazon-advertising-products"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"availability":{"nullable":true,"type":"string","enum":["IN_STOCK","IN_STOCK_SCARCE","OUT_OF_STOCK","PREORDER","LEADTIME","AVAILABLE_DATE"]},"eligibilityStatus":{"nullable":true,"type":"string","enum":["ELIGIBLE","INELIGIBLE"]},"ineligibilityCodes":{"type":"array","items":{"type":"string"}},"ineligibilityReasons":{"type":"array","items":{"type":"string"}},"basisPrice":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"],"additionalProperties":false},"bestSellerRank":{"nullable":true,"type":"string"},"firstAvailabilityDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"categoryName":{"nullable":true,"type":"string"},"brandName":{"nullable":true,"type":"string"},"variationList":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","active","connection","country","availability","eligibilityStatus","ineligibilityCodes","ineligibilityReasons","basisPrice","bestSellerRank","firstAvailabilityDate","categoryName","brandName","variationList","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/seller-product-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window, grouped by ASIN + SKU + connection + country + currency (the same ASIN sells in several marketplaces with different prices and currencies). Unlike the rest of the API, this resource paginates with `limit`/`offset` (an aggregated row has no id to use as a cursor) and `has_more` tells whether another page follows. Monetary amounts are decimal strings. `sessions`, `page_views`, `buy_box_percentage`, `conversion_rate` and `rank` are `null`, never `0`, when Amazon did not report them: its traffic report only covers products with activity. `conversion_rate` is `orders / sessions` here, not `orders / clicks` as in `campaign_metrics`. The economics block (`referral_fee`, `fba_fulfilment_fee`, `storage_fee`, `other_fees`, `amazon_fees`, `net_sales`, `net_units`, `margin_before_ads`, `refunded_sales`, `refunded_units`) comes from Amazon Data Kiosk and has three caveats: every amount excludes VAT, as `sales` does, but it comes from a different Amazon source, so `net_sales` does not reconcile exactly with `sales` minus refunds; storage fees are booked on a single day of the month, so read margins over at least a month; and refunds are booked on the refund date, not the sale date. It is `null` when there is no economics data for the product in the window (it lands 48-72 h late). No field in it includes advertising: take ad spend from the advertising metrics. For that reason `margin_before_ads` is higher than the product margin shown in the Epinium app, which also subtracts the ad spend Amazon attributes to the product. With `group_by`, rows are aggregated across products (see the parameter): sums are summed, `stock` is the sum of the latest stock of each product, `days_of_coverage` is recomputed on the aggregates (stock summed over the products that reported it, units over all of them), `buy_box_percentage` and `b2b_buy_box_percentage` are weighted by page views, and `rank`, `price` and `fulfillment_channel` are `null`. `total_count` then counts groups, or group-periods when `granularity` is not `total`.","summary":"Seller Central sales and traffic per product, from the account's report history","tags":["seller-product-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`). Every metrics call costs a charge per day of the window (1 to 8 credits per day depending on the resource) plus 1 credit per row returned, so a grouped call costs about the window charge alone, and a shorter window is usually what lowers the price most. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter. `cluster` gives one row per product cluster (the `clusters` resource), with its id in `cluster` and its name in `cluster_name`. A product in several clusters counts in full in each of them, so the cluster rows do NOT add up to the account total, and products in no cluster are left out. It combines with `connection` and `country`, and with the `cluster` filter to choose which clusters come back.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country","cluster"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country","cluster"]}}]}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"product","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`.","schema":{"type":"string","pattern":"^[A-Z0-9]{10}$"}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["sales","units","orders","sessions","page_views","rank","conversion_rate","net_sales","amazon_fees","margin_before_ads","days_of_coverage","b2b_sales"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["seller_product_metrics"]},"product":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"cluster":{"nullable":true,"description":"Product cluster of the row, only with `group_by=cluster`; `null` otherwise.","type":"string","pattern":"^[a-f0-9]{24}$"},"cluster_name":{"nullable":true,"description":"Name of the product cluster, only with `group_by=cluster`; `null` otherwise.","type":"string"},"currency":{"type":"string"},"date":{"type":"string"},"sales":{"type":"string","description":"Product sales excluding VAT: the item price of each order line minus the VAT Amazon itemizes on it. Lines where Amazon does not itemize VAT (pending orders, some marketplaces) count at the price charged. Refunds are not deducted."},"units":{"type":"number"},"orders":{"type":"number"},"sessions":{"nullable":true,"description":"Sessions from Amazon's Sales and Traffic data. `null` when Amazon did not report them. Today traffic is only stored for the product-days with orders: a day with visits and no sale has none, so traffic totals undercount and the ratios built on them lean high.","type":"number"},"page_views":{"nullable":true,"description":"Page views from Amazon's Sales and Traffic data. `null` when Amazon did not report them. Today traffic is only stored for the product-days with orders: a day with visits and no sale has none, so traffic totals undercount and the ratios built on them lean high.","type":"number"},"buy_box_percentage":{"nullable":true,"description":"Share of page views that showed your offer in the Buy Box, from 0 to 100 as Amazon reports it (not a fraction), weighted by page views over the window. `null` when Amazon did not report it. Today traffic is only stored for the product-days with orders: a day with visits and no sale has none, so traffic totals undercount and the ratios built on them lean high.","type":"number"},"conversion_rate":{"nullable":true,"description":"Conversion rate (CVR): orders per session as a fraction (0.29 = 29%). Not the advertising conversion rate, which is orders per click. `null` when no sessions were reported. Today traffic is only stored for the product-days with orders: a day with visits and no sale has none, so traffic totals undercount and the ratios built on them lean high. So today it overstates conversion: do not judge a listing or a bid by it alone.","type":"number"},"rank":{"nullable":true,"description":"Best Seller Rank (BSR): the median rank over the window, lower is better, with no category. The category comes with `expand=salesRanks` on `amazon_seller_products`. `null` when Amazon did not report it, and with `group_by`.","type":"number"},"referral_fee":{"nullable":true,"description":"Amazon referral fee, excluding VAT.","type":"string"},"fba_fulfilment_fee":{"nullable":true,"description":"FBA fulfilment fee, excluding VAT.","type":"string"},"storage_fee":{"nullable":true,"description":"FBA storage fees (monthly, aged inventory and surcharges), excluding VAT. Amazon books them on a single day of the month, so a daily row or a window shorter than a month over- or under-states it.","type":"string"},"other_fees":{"nullable":true,"description":"Every other Amazon fee, excluding VAT. Can be negative: it includes refunded commissions and FBA inventory reimbursements.","type":"string"},"amazon_fees":{"nullable":true,"description":"Sum of the four fees above: what Amazon charged for the product, excluding VAT. Advertising is NOT included.","type":"string"},"net_sales":{"nullable":true,"description":"Product sales excluding VAT and net of refunds, from Amazon economics data, plus the shipping charged to the buyer on the orders that pay for it (also excluding VAT). It comes from a different Amazon source than `sales`, which carries no shipping, so the two do not reconcile. Refunds count on the refund date, not on the date of the original sale. Can be negative when refunds of earlier sales exceed the sales of the window.","type":"string"},"net_units":{"nullable":true,"description":"Units ordered minus units refunded.","type":"number"},"margin_before_ads":{"nullable":true,"description":"`net_sales - amazon_fees`, excluding VAT: the margin before advertising and before product cost (COGS). Not a profit figure. Subtract the ad spend from the advertising metrics to get the margin after ads.","type":"string"},"breakeven_acos":{"nullable":true,"description":"The advertising cost of sale (ACoS) above which this product stops being profitable before any other cost: `(margin_before_ads - product cost * net_units) / net_sales`, as a fraction (0.332 = 33.2%), not a percentage. Can be negative (already losing money before advertising) or above 1. `null` when there is no product cost on file, no economics data for the window, the cost currency does not match `currency` (this resource does not convert currencies), or the account's plan does not include product cost (Business and Master only).","type":"number"},"refunded_sales":{"nullable":true,"description":"Refunded product sales, excluding VAT. Booked on the refund date, not on the date of the original sale.","type":"string"},"refunded_units":{"nullable":true,"description":"Refunded units, booked on the refund date, not on the date of the original sale.","type":"number"},"stock":{"nullable":true,"description":"Latest stock reported in the window, not a sum. With `group_by`, the sum of each product's latest value when `country` is one of the dimensions, and `null` otherwise: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. For FBA it is everything Amazon holds for the SKU, including inbound, reserved and unfulfillable units; for FBM it is the quantity set on the listing.","type":"number"},"fulfillment_channel":{"nullable":true,"description":"`FBA` or `FBM` on the last day of the window (a SKU can switch channels). `null` with `group_by`.","type":"string"},"price":{"nullable":true,"description":"Latest listing price in the window, as the buyer sees it (VAT included where it applies). `null` with `group_by`.","type":"string"},"days_of_coverage":{"nullable":true,"description":"Days the current stock lasts at the pace of the window: `stock / (units / days in the window)`. The days are those of the requested window, not only the days with sales. `null` with any `granularity` other than `total`, with a `group_by` that does not include `country` (see `stock`), when the product sold nothing in the window, or when no stock was reported. For FBA it counts all units Amazon holds, not only the sellable ones.","type":"number"},"b2b_sales":{"nullable":true,"description":"Amazon Business (B2B) sales, VAT included where it applies. It comes from a different Amazon report than `sales`, which excludes VAT, so it is not a strict subset of it.","type":"string"},"b2b_units":{"nullable":true,"description":"Amazon Business (B2B) units, a subset of `units`.","type":"number"},"b2b_order_items":{"nullable":true,"description":"Amazon Business (B2B) order items. Counts order lines, not orders.","type":"number"},"b2b_sessions":{"nullable":true,"description":"Amazon Business (B2B) sessions.","type":"number"},"b2b_page_views":{"nullable":true,"description":"Amazon Business (B2B) page views.","type":"number"},"b2b_buy_box_percentage":{"nullable":true,"description":"Amazon Business (B2B) buy box percentage, 0-100 as Amazon reports it, weighted by B2B page views over the window (the share of B2B page views that showed your offer in the buy box). `null` without B2B page views.","type":"number"}},"required":["object","product","asin","sku","connection","country","cluster","cluster_name","currency","sales","units","orders","sessions","page_views","buy_box_percentage","conversion_rate","rank","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","amazon_fees","net_sales","net_units","margin_before_ads","breakeven_acos","refunded_sales","refunded_units","stock","fulfillment_channel","price","days_of_coverage","b2b_sales","b2b_units","b2b_order_items","b2b_sessions","b2b_page_views","b2b_buy_box_percentage"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/vendor-product-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window, grouped by ASIN + connection + country + currency (the same ASIN sells in several marketplaces with different prices and currencies; the SKU is not part of the key here, unlike `seller_product_metrics`). Unlike the rest of the API, this resource paginates with `limit`/`offset` (an aggregated row has no id to use as a cursor) and `has_more` tells whether another page follows. Monetary amounts are decimal strings. There is deliberately NO single `sales` field: Vendor Central has two business models and Amazon does not report them symmetrically. Manufacturing (Amazon makes the product under licence) reports ordered, shipped and net received, while sourcing (you sell wholesale to Amazon) reports only shipped and net received. Read the pair that matches how you sell. Vendor has no sessions or conversion rate at all; `glance_views` is the traffic metric, and it is `null`, never `0`, when Amazon did not report it, as are `rank` and both `*_sellable_units`. The `*_sellable_units` fields are the latest inventory snapshot in the window, not a sum. With `group_by`, rows are aggregated across products (see the parameter): sums are summed, the snapshot fields (both `*_sellable_units` and the other levels read on the last day of the window with data) are the sum of the latest value of each product, `days_of_coverage` is recomputed on the aggregates (stock summed over the products that reported it, units over all of them), and `rank`, `sourcing_lead_time_days` and the sourcing rates are `null`. `total_count` then counts groups, or group-periods when `granularity` is not `total`.","summary":"Vendor Central sales per product, split by manufacturing and sourcing, from the account's report history","tags":["vendor-product-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`). Every metrics call costs a charge per day of the window (1 to 8 credits per day depending on the resource) plus 1 credit per row returned, so a grouped call costs about the window charge alone, and a shorter window is usually what lowers the price most. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter. `cluster` gives one row per product cluster (the `clusters` resource), with its id in `cluster` and its name in `cluster_name`. A product in several clusters counts in full in each of them, so the cluster rows do NOT add up to the account total, and products in no cluster are left out. It combines with `connection` and `country`, and with the `cluster` filter to choose which clusters come back.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country","cluster"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country","cluster"]}}]}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"product","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`.","schema":{"type":"string","pattern":"^[A-Z0-9]{10}$"}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["units","glance_views","rank","manufacturing_ordered_sales","manufacturing_ordered_units","manufacturing_shipped_sales","manufacturing_shipped_units","manufacturing_shipped_cogs","manufacturing_net_received_sales","manufacturing_net_received_units","sourcing_shipped_sales","sourcing_shipped_units","sourcing_shipped_cogs","sourcing_net_received_sales","sourcing_net_received_units","sourcing_customer_returns","manufacturing_customer_returns","sourcing_confirmed_units","days_of_coverage"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["vendor_product_metrics"]},"product":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"cluster":{"nullable":true,"description":"Product cluster of the row, only with `group_by=cluster`; `null` otherwise.","type":"string","pattern":"^[a-f0-9]{24}$"},"cluster_name":{"nullable":true,"description":"Name of the product cluster, only with `group_by=cluster`; `null` otherwise.","type":"string"},"currency":{"type":"string"},"date":{"type":"string"},"units":{"type":"number"},"manufacturing_ordered_sales":{"type":"string"},"manufacturing_ordered_units":{"type":"number"},"manufacturing_shipped_sales":{"type":"string"},"manufacturing_shipped_units":{"type":"number"},"manufacturing_shipped_cogs":{"type":"string"},"manufacturing_net_received_sales":{"type":"string"},"manufacturing_net_received_units":{"type":"number"},"sourcing_shipped_sales":{"type":"string"},"sourcing_shipped_units":{"type":"number"},"sourcing_shipped_cogs":{"type":"string"},"sourcing_net_received_sales":{"type":"string"},"sourcing_net_received_units":{"type":"number"},"glance_views":{"nullable":true,"type":"number"},"manufacturing_sellable_units":{"nullable":true,"type":"number"},"sourcing_sellable_units":{"nullable":true,"type":"number"},"rank":{"nullable":true,"description":"Best Seller Rank (BSR): the median rank over the window, lower is better, with no category. The category comes with `expand=salesRanks` on `amazon_vendor_products`. `null` when Amazon did not report it, and with `group_by`.","type":"number"},"sourcing_customer_returns":{"nullable":true,"description":"Units returned by customers, sourcing view, summed over the window.","type":"number"},"manufacturing_customer_returns":{"nullable":true,"description":"Units returned by customers, manufacturing view, summed over the window.","type":"number"},"manufacturing_unfilled_ordered_units":{"nullable":true,"description":"Units ordered (or pre-ordered) by customers that have not shipped yet, on the last day of the window with data. A level, not a sum. With `group_by`, the sum of each product's latest value. Manufacturing only: Amazon does not report it for sourcing.","type":"number"},"sourcing_confirmed_units":{"nullable":true,"description":"Purchase order units the vendor confirmed to ship to Amazon, summed over the window.","type":"number"},"sourcing_open_po_units":{"nullable":true,"description":"Units in open purchase orders (confirmed, not yet received) on the last day of the window with data. A level, not a sum. With `group_by`, the sum of each product's latest value.","type":"number"},"sourcing_most_recent_submitted_units":{"nullable":true,"description":"Units Amazon ordered in the most recent purchase orders of the week, on the last day of the window with data.","type":"number"},"sourcing_received_fill_rate":{"nullable":true,"description":"Received units / confirmed units, as a fraction (0.95 = 95%), procurable ASINs only. Average of Amazon's daily rate over the window. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_vendor_confirmation_rate":{"nullable":true,"description":"Confirmed units / units Amazon asked for, as a fraction, procurable ASINs only. Average of Amazon's daily rate over the window. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_lead_time_days":{"nullable":true,"description":"Days from the purchase order to the inventory arriving at an Amazon fulfilment centre. Average over the window. `null` with `group_by`: Amazon reports the average without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_procurable_oos_rate":{"nullable":true,"description":"Share of glance views that found the product out of stock, procurable ASINs only, as a fraction. Average of Amazon's daily rate. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_sell_through_rate":{"nullable":true,"description":"(Shipped units - customer returns) / (sellable on-hand + net received units), as a fraction. Average of Amazon's daily rate. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_sourceable_oos_rate":{"nullable":true,"description":"Share of glance views that found the product out of stock, among ASINs with a vendor able to supply them, as a fraction. Average of Amazon's daily rate. `null` with `group_by`: Amazon reports the rate without its components, so it cannot be re-aggregated.","type":"number"},"sourcing_aged_90_plus_units":{"nullable":true,"description":"Sellable units that have been 90 days or more in Amazon's warehouses, on the last day of the window with data.","type":"number"},"sourcing_unsellable_on_hand_units":{"nullable":true,"description":"Unsellable units in Amazon's fulfilment centres, on the last day of the window with data.","type":"number"},"sourcing_sellable_in_transit_units":{"nullable":true,"description":"Sellable units in transit, on the last day of the window with data.","type":"number"},"sourcing_unsellable_in_transit_units":{"nullable":true,"description":"Unsellable units in transit, on the last day of the window with data.","type":"number"},"days_of_coverage":{"nullable":true,"description":"Days the current stock lasts at the pace of the window: `sourcing_sellable_units` (or `manufacturing_sellable_units` if there is none) / (`units` / days in the window). The days are those of the requested window. `null` with any `granularity` other than `total`, when the product sold nothing in the window, or when no stock was reported, which today is always the case for manufacturing-only vendors.","type":"number"}},"required":["object","product","asin","sku","connection","country","cluster","cluster_name","currency","units","manufacturing_ordered_sales","manufacturing_ordered_units","manufacturing_shipped_sales","manufacturing_shipped_units","manufacturing_shipped_cogs","manufacturing_net_received_sales","manufacturing_net_received_units","sourcing_shipped_sales","sourcing_shipped_units","sourcing_shipped_cogs","sourcing_net_received_sales","sourcing_net_received_units","glance_views","manufacturing_sellable_units","sourcing_sellable_units","rank","sourcing_customer_returns","manufacturing_customer_returns","manufacturing_unfilled_ordered_units","sourcing_confirmed_units","sourcing_open_po_units","sourcing_most_recent_submitted_units","sourcing_received_fill_rate","sourcing_vendor_confirmation_rate","sourcing_lead_time_days","sourcing_procurable_oos_rate","sourcing_sell_through_rate","sourcing_sourceable_oos_rate","sourcing_aged_90_plus_units","sourcing_unsellable_on_hand_units","sourcing_sellable_in_transit_units","sourcing_unsellable_in_transit_units","days_of_coverage"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/cascade":{"get":{"description":"Same calculation as the \"Cascada del periodo\" chart in Rentabilidad: `net sales - fees/logistics - advertising - product cost - variable expenses = contribution margin`, and `contribution margin - fixed expenses = net profit`, with the previous period of equal length for comparison. Own expenses come in `own_expenses`: the variable ones are already in the `variable_expenses` section, broken down there by expense category; the fixed ones (salaries, software, agency fee) are subtracted after contribution margin, down to `net_profit`. Fixed expenses belong to the whole account, so with `connection`, `country` or `cluster`, or with a credential that cannot read every sales connection, they and `net_profit` come back `null` and `fixed_unavailable` says why, when the account has fixed expenses; without any, `net_profit` is always there. Unlike every other resource in this API, amounts ARE converted: `currency` is a required parameter, and every amount in the response lands in it using the daily rate from `fx_rates_daily` (a day without a rate falls back to an approximate one, never an error). Free and Guru plans receive the same shape with `cogs`/`product_cost` always `0` and `includes_product_cost: false` - see that field before reading those as \"no cost\", they mean \"not on this plan\". `connection` and `country` restrict to a single sales connection/marketplace; without them, every Amazon Seller/Vendor connection the credential can read is summed. `cluster` restricts the cascade to the products of one or more product clusters, same semantics as on the metrics resources - a cluster that resolves to no products in scope returns an empty cascade, not an error. Advertising under `cluster` only counts spend attributed to those products: Sponsored Brands and campaign spend not tied to a specific product are left out. A `connection` outside the ones this credential can read comes back as an empty cascade, not an error - same criterion as every other resource in this API. Low or zero `coverage` right after loading costs is rarely \"no costs\": each cost applies from its `valid_from` (one loaded without a date applies from the upload day, so earlier periods stay uncovered - suggest reloading it with an earlier date if it already applied), cost reaches the margin only once Amazon confirms the sales (see `/v1/pnl/freshness`, a few days), and cost-import rows are rejected when the SKU/marketplace is not in that account.","summary":"Waterfall P&L for the period: net sales minus fees, advertising, product cost and own expenses, down to net profit","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"granularity","in":"query","description":"`month` (default) returns one row per calendar month. `day` returns one row per day, capped at 366 days.","schema":{"default":"month","type":"string","enum":["month","day"]}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_cascade"]},"currency":{"type":"string"},"includes_product_cost":{"type":"boolean","description":"Whether `cogs`/`product_cost` reflect real product cost. `false` on Free/Guru plans: those amounts are always `0` there, not because nothing was spent but because the plan does not include product cost. Upgrade to Business to see it."},"months":{"type":"array","items":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"partial":{"type":"boolean","description":"Current month, trimmed by the window, or closed less than 5 days ago: some charges (storage, late refunds) may still be missing."}},"required":["categories","sections","month","partial"],"additionalProperties":false}},"periods":{"type":"array","items":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."},"period":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}],"description":"`YYYY-MM` with `granularity=month`, `YYYY-MM-DD` with `granularity=day`."},"partial":{"type":"boolean"},"advertising":{"description":"Breakdown of the `ads` category by platform and native line. Their amounts sum exactly to `categories.ads`.","type":"array","items":{"type":"object","properties":{"ad_platform":{"type":"string","enum":["amazon_ads"]},"line":{"type":"string","enum":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping","own_expense","promo_subscribe_save","promo_promotions_manager","promo_other","promo_shipping","shipping_income","fba_inventory_reimbursement","promotion_fees","refund_commission","return_processing_fee","digital_services_fee","closing_fee","fba_inbound_fee","removal_disposal_fee"]},"amount":{"type":"number"}},"required":["ad_platform","line","amount"],"additionalProperties":false}}},"required":["categories","sections","period","partial"],"additionalProperties":false}},"storage_is_monthly":{"type":"boolean","description":"With `granularity=day`, Amazon still books storage fees on a single day of the month: `true` warns that a daily row or a short window over- or under-states it."},"totals":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false},"previous_totals":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false},"previous_periods":{"nullable":true,"type":"array","items":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."},"period":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}],"description":"`YYYY-MM` with `granularity=month`, `YYYY-MM-DD` with `granularity=day`."},"partial":{"type":"boolean"},"advertising":{"description":"Breakdown of the `ads` category by platform and native line. Their amounts sum exactly to `categories.ads`.","type":"array","items":{"type":"object","properties":{"ad_platform":{"type":"string","enum":["amazon_ads"]},"line":{"type":"string","enum":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping","own_expense","promo_subscribe_save","promo_promotions_manager","promo_other","promo_shipping","shipping_income","fba_inventory_reimbursement","promotion_fees","refund_commission","return_processing_fee","digital_services_fee","closing_fee","fba_inbound_fee","removal_disposal_fee"]},"amount":{"type":"number"}},"required":["ad_platform","line","amount"],"additionalProperties":false}}},"required":["categories","sections","period","partial"],"additionalProperties":false}},"coverage":{"nullable":true,"description":"`null` when the window has no sales.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"estimated_sales":{"type":"number","description":"Part of `covered_sales` whose product cost is estimated: the stock group sold more units than its recorded purchases left, so those sales take the last average cost. `0` without purchases."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","estimated_sales","total_sales"],"additionalProperties":false},"own_expenses":{"nullable":true,"description":"`null` on Free/Guru plans, like `cogs` (own expenses go with the product cost plan), and when the credential can read no sales connection.","type":"object","properties":{"fixed_unavailable":{"nullable":true,"description":"Why fixed expenses and net profit are not shown: `filtered` (a `connection`, `country` or `cluster` filter - they belong to the whole account, drop the filter to see them) or `partial_access` (this credential cannot read every sales connection of the account). `null` when they are shown, and always when the account has no fixed expenses.","type":"string","enum":["filtered","partial_access"]},"periods":{"type":"array","items":{"type":"object","properties":{"variable":{"type":"object","additionalProperties":{"type":"number"},"description":"Breakdown of the `variable_expenses` section by expense category: it adds up to that section."},"fixed":{"nullable":true,"description":"`null` when `fixed_unavailable` is set.","type":"object","additionalProperties":{"type":"number"}},"net_profit":{"nullable":true,"description":"Contribution margin minus fixed expenses. `null` when `fixed_unavailable` is set.","type":"number"},"period":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]}},"required":["variable","fixed","net_profit","period"],"additionalProperties":false}},"totals":{"type":"object","properties":{"variable":{"type":"object","additionalProperties":{"type":"number"},"description":"Breakdown of the `variable_expenses` section by expense category: it adds up to that section."},"fixed":{"nullable":true,"description":"`null` when `fixed_unavailable` is set.","type":"object","additionalProperties":{"type":"number"}},"net_profit":{"nullable":true,"description":"Contribution margin minus fixed expenses. `null` when `fixed_unavailable` is set.","type":"number"}},"required":["variable","fixed","net_profit"],"additionalProperties":false},"previous_totals":{"type":"object","properties":{"variable":{"type":"object","additionalProperties":{"type":"number"},"description":"Breakdown of the `variable_expenses` section by expense category: it adds up to that section."},"fixed":{"nullable":true,"description":"`null` when `fixed_unavailable` is set.","type":"object","additionalProperties":{"type":"number"}},"net_profit":{"nullable":true,"description":"Contribution margin minus fixed expenses. `null` when `fixed_unavailable` is set.","type":"number"}},"required":["variable","fixed","net_profit"],"additionalProperties":false}},"required":["fixed_unavailable","periods","totals","previous_totals"],"additionalProperties":false}},"required":["object","currency","includes_product_cost","months","periods","storage_is_monthly","totals","previous_totals","previous_periods","coverage","own_expenses"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/products":{"get":{"description":"Same per-product breakdown as the \"Margen por producto\" table in Rentabilidad, one row per catalog product plus an \"unassigned\" row (`product: null`) for sales pnl_lines could not match. Same currency-conversion exception as `/v1/pnl/cascade`: `currency` is required and every amount lands in it. Paginates with `limit`/`offset`, not a cursor - rows are aggregates, not records with an id. `order_by` picks the sort field (default `netSales`); `search` matches the SKU or ASIN, or the catalog title of the product; `cluster` restricts the rows to the products of one or more product clusters, and combines with `search`. Advertising under `cluster` only counts spend attributed to those products: Sponsored Brands and campaign spend not tied to a specific product are left out. Free and Guru plans receive every row with `cogs`/`product_cost` at `0` and `includes_product_cost: false`. A `connection` outside the ones this credential can read comes back as an empty list, not an error.","summary":"P&L with product cost per product, paginated and sortable","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"search","in":"query","description":"Case-insensitive substring match over the product title. Resolved against the catalog, then matched by SKU/ASIN - a product with no catalog match cannot be found this way.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","description":"Page size. Paginate with `offset`, not a cursor: these rows are aggregates over the window, not records with an id.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order_by","in":"query","description":"Field to sort by: `netSales` (default), `contributionMargin`, `marginPct`, `coverage`, a P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`) or a section (`revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`).","schema":{"default":"netSales","type":"string","enum":["netSales","contributionMargin","marginPct","coverage","sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses","revenue","fees_logistics","advertising","product_cost","variable_expenses"]}},{"name":"order","in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_product"]},"product":{"nullable":true,"description":"FK to `/v1/products`. `null` for the \"unassigned\" row: sales pnl_lines could not match to a catalog product.","type":"string","pattern":"^[a-f0-9]{24}$"},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"sku":{"nullable":true,"description":"SKU on Seller, ASIN on Vendor. `null` for the \"unassigned\" row.","type":"string"},"title":{"nullable":true,"type":"string"},"image":{"nullable":true,"type":"string"},"amounts":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false},"contribution_margin":{"type":"number","description":"Sum of every section: `revenue + fees_logistics + advertising + product_cost + variable_expenses`."},"margin_pct":{"type":"number","description":"contribution_margin / net sales, as a fraction (0.25 = 25%). `0` when net sales are `0` for the window, not a real 0% margin."},"coverage":{"nullable":true,"description":"`null` when the product has no sales in the window.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"estimated_sales":{"type":"number","description":"Part of `covered_sales` whose product cost is estimated: the stock group sold more units than its recorded purchases left, so those sales take the last average cost. `0` without purchases."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","estimated_sales","total_sales"],"additionalProperties":false},"previous":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false}},"required":["object","product","connection","country","sku","title","image","amounts","contribution_margin","margin_pct","coverage","previous"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"},"includes_product_cost":{"type":"boolean","description":"Same meaning as on `/v1/pnl/cascade`: `false` on Free/Guru plans, where `cogs`/`product_cost` are always `0` on every row."}},"required":["object","data","has_more","currency","includes_product_cost"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/products/{id}":{"get":{"description":"Same ficha as the product margin section in Rentabilidad: one row per month, with the breakdown by native P&L line (e.g. `referral_fee`, `fba_fulfilment_fee`, `cogs`) inside each category. Scoped to the product's own sales connection and country, not to a `connection`/`country` filter - there is none here, the id already picks the product. Same currency-conversion exception as `/v1/pnl/cascade`. `404` when `id` does not exist, is not a catalog product (seller/vendor) or falls outside the connections this credential can read - never partial data for a product you cannot see. Free and Guru plans receive the same shape with `cogs`/`product_cost` always `0` and `includes_product_cost: false`. Read a low `coverage` the same way as on `/v1/pnl/cascade`.","summary":"P&L with product cost for one product, by month and native line","tags":["pnl"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_product_detail"]},"includes_product_cost":{"type":"boolean","description":"Same meaning as on `/v1/pnl/cascade`: `false` on Free/Guru plans, where `cogs`/`product_cost` are always `0`."},"months":{"type":"array","items":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"partial":{"type":"boolean","description":"Current month, trimmed by the window, or closed less than 5 days ago: some charges (storage, late refunds) may still be missing."},"lines":{"type":"object","properties":{"ordered_product_sales":{"type":"number"},"refunded_product_sales":{"type":"number"},"referral_fee":{"type":"number"},"fba_fulfilment_fee":{"type":"number"},"storage_fee":{"type":"number"},"other_fees":{"type":"number"},"vendor_sales":{"type":"number"},"sp_spend":{"type":"number"},"sb_spend":{"type":"number"},"sd_spend":{"type":"number"},"cogs":{"type":"number"},"unsellable_returns":{"type":"number"},"own_shipping":{"type":"number"},"own_expense":{"type":"number"},"promo_subscribe_save":{"type":"number"},"promo_promotions_manager":{"type":"number"},"promo_other":{"type":"number"},"promo_shipping":{"type":"number"},"shipping_income":{"type":"number"},"fba_inventory_reimbursement":{"type":"number"},"promotion_fees":{"type":"number"},"refund_commission":{"type":"number"},"return_processing_fee":{"type":"number"},"digital_services_fee":{"type":"number"},"closing_fee":{"type":"number"},"fba_inbound_fee":{"type":"number"},"removal_disposal_fee":{"type":"number"}},"required":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping","own_expense","promo_subscribe_save","promo_promotions_manager","promo_other","promo_shipping","shipping_income","fba_inventory_reimbursement","promotion_fees","refund_commission","return_processing_fee","digital_services_fee","closing_fee","fba_inbound_fee","removal_disposal_fee"],"additionalProperties":false}},"required":["categories","sections","month","partial","lines"],"additionalProperties":false}},"totals":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."},"lines":{"type":"object","properties":{"ordered_product_sales":{"type":"number"},"refunded_product_sales":{"type":"number"},"referral_fee":{"type":"number"},"fba_fulfilment_fee":{"type":"number"},"storage_fee":{"type":"number"},"other_fees":{"type":"number"},"vendor_sales":{"type":"number"},"sp_spend":{"type":"number"},"sb_spend":{"type":"number"},"sd_spend":{"type":"number"},"cogs":{"type":"number"},"unsellable_returns":{"type":"number"},"own_shipping":{"type":"number"},"own_expense":{"type":"number"},"promo_subscribe_save":{"type":"number"},"promo_promotions_manager":{"type":"number"},"promo_other":{"type":"number"},"promo_shipping":{"type":"number"},"shipping_income":{"type":"number"},"fba_inventory_reimbursement":{"type":"number"},"promotion_fees":{"type":"number"},"refund_commission":{"type":"number"},"return_processing_fee":{"type":"number"},"digital_services_fee":{"type":"number"},"closing_fee":{"type":"number"},"fba_inbound_fee":{"type":"number"},"removal_disposal_fee":{"type":"number"}},"required":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping","own_expense","promo_subscribe_save","promo_promotions_manager","promo_other","promo_shipping","shipping_income","fba_inventory_reimbursement","promotion_fees","refund_commission","return_processing_fee","digital_services_fee","closing_fee","fba_inbound_fee","removal_disposal_fee"],"additionalProperties":false,"description":"Amount per native P&L line (e.g. `referral_fee`, `fba_fulfilment_fee`, `cogs`). Each category is the sum of its lines."}},"required":["categories","sections","lines"],"additionalProperties":false},"previous_totals":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."},"lines":{"type":"object","properties":{"ordered_product_sales":{"type":"number"},"refunded_product_sales":{"type":"number"},"referral_fee":{"type":"number"},"fba_fulfilment_fee":{"type":"number"},"storage_fee":{"type":"number"},"other_fees":{"type":"number"},"vendor_sales":{"type":"number"},"sp_spend":{"type":"number"},"sb_spend":{"type":"number"},"sd_spend":{"type":"number"},"cogs":{"type":"number"},"unsellable_returns":{"type":"number"},"own_shipping":{"type":"number"},"own_expense":{"type":"number"},"promo_subscribe_save":{"type":"number"},"promo_promotions_manager":{"type":"number"},"promo_other":{"type":"number"},"promo_shipping":{"type":"number"},"shipping_income":{"type":"number"},"fba_inventory_reimbursement":{"type":"number"},"promotion_fees":{"type":"number"},"refund_commission":{"type":"number"},"return_processing_fee":{"type":"number"},"digital_services_fee":{"type":"number"},"closing_fee":{"type":"number"},"fba_inbound_fee":{"type":"number"},"removal_disposal_fee":{"type":"number"}},"required":["ordered_product_sales","refunded_product_sales","referral_fee","fba_fulfilment_fee","storage_fee","other_fees","vendor_sales","sp_spend","sb_spend","sd_spend","cogs","unsellable_returns","own_shipping","own_expense","promo_subscribe_save","promo_promotions_manager","promo_other","promo_shipping","shipping_income","fba_inventory_reimbursement","promotion_fees","refund_commission","return_processing_fee","digital_services_fee","closing_fee","fba_inbound_fee","removal_disposal_fee"],"additionalProperties":false,"description":"Amount per native P&L line (e.g. `referral_fee`, `fba_fulfilment_fee`, `cogs`). Each category is the sum of its lines."}},"required":["categories","sections","lines"],"additionalProperties":false},"coverage":{"nullable":true,"description":"`null` when the product has no sales in the window.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"estimated_sales":{"type":"number","description":"Part of `covered_sales` whose product cost is estimated: the stock group sold more units than its recorded purchases left, so those sales take the last average cost. `0` without purchases."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","estimated_sales","total_sales"],"additionalProperties":false},"currency":{"type":"string"}},"required":["object","includes_product_cost","months","totals","previous_totals","coverage","currency"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/channels":{"get":{"description":"Same per-connection breakdown as the channel card in Rentabilidad: one row per sales connection (Amazon Seller or Vendor), ordered by net sales. No `limit`/`offset`: the row count is bounded by the sales connections this credential can read, not by catalog size. Same currency-conversion exception as `/v1/pnl/cascade`. Free and Guru plans receive every row with `cogs`/`product_cost` at `0` and `includes_product_cost: false`. A `connection` outside the ones this credential can read comes back as an empty list, not an error.","summary":"P&L with product cost per sales connection","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_channel"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"channel":{"type":"string","enum":["seller","vendor"]},"platform":{"type":"string","description":"Sales platform of the connection. Always `amazon` today: Shopify and WooCommerce do not feed this P&L yet."},"amounts":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false},"contribution_margin":{"type":"number","description":"Sum of every section: `revenue + fees_logistics + advertising + product_cost + variable_expenses`."},"margin_pct":{"type":"number","description":"contribution_margin / net sales, as a fraction (0.25 = 25%). `0` when net sales are `0` for the window, not a real 0% margin."},"previous":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false}},"required":["object","connection","channel","platform","amounts","contribution_margin","margin_pct","previous"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"},"includes_product_cost":{"type":"boolean","description":"Same meaning as on `/v1/pnl/cascade`: `false` on Free/Guru plans, where `cogs`/`product_cost` are always `0` on every row."}},"required":["object","data","has_more","currency","includes_product_cost"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/clusters":{"get":{"description":"Same per-cluster breakdown as the \"By cluster\" tab of \"Margen por producto\" in Rentabilidad: one row per product cluster (the `clusters` resource), use it INSTEAD of calling `/v1/pnl/cascade` once per cluster. A product in several clusters counts in full in each of them, so the rows do NOT add up to the account total (`/v1/pnl/cascade` without `cluster`), and products in no cluster, plus amounts with no catalog product (campaign-level advertising, account fees), are left out. Membership is today's: a product added to a cluster now also counts in its earlier months. Clusters with no P&L rows in the window still come back, with `has_activity: false`, last. Same currency-conversion exception as `/v1/pnl/cascade`: `currency` is required and every amount lands in it. Paginates with `limit`/`offset`; `order_by` picks the sort field (default `contributionMargin`); `cluster` restricts the rows to those clusters. Advertising only counts spend attributed to the cluster's products: Sponsored Brands and campaign spend not tied to a product are left out. Free and Guru plans receive every row with `cogs`/`product_cost` at `0` and `includes_product_cost: false`. A `connection` outside the ones this credential can read comes back as an empty list, not an error.","summary":"P&L with product cost per product cluster, paginated and sortable","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"limit","in":"query","description":"Page size. Paginate with `offset`, not a cursor: these rows are aggregates over the window, not records with an id.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order_by","in":"query","description":"Field to sort by: `contributionMargin` (default), `netSales`, `marginPct`, `coverage`, a P&L category or a section, same list as `/v1/pnl/products`. Clusters with no P&L rows in the window always come last.","schema":{"default":"contributionMargin","type":"string","enum":["netSales","contributionMargin","marginPct","coverage","sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses","revenue","fees_logistics","advertising","product_cost","variable_expenses"]}},{"name":"order","in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_cluster"]},"cluster":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"FK to `/v1/clusters`."},"name":{"type":"string"},"product_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Every catalog product in the cluster, sold or not in the window. Not narrowed by `connection`/`country`: cluster membership is account-wide."},"has_activity":{"type":"boolean","description":"`false` when none of its products has a P&L row in the window: every amount is `0` and the cluster sorts last."},"amounts":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false},"contribution_margin":{"type":"number","description":"Sum of every section: `revenue + fees_logistics + advertising + product_cost + variable_expenses`."},"margin_pct":{"type":"number","description":"contribution_margin / net sales, as a fraction (0.25 = 25%). `0` when net sales are `0` for the window, not a real 0% margin."},"coverage":{"nullable":true,"description":"`null` when the cluster has no sales in the window.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"estimated_sales":{"type":"number","description":"Part of `covered_sales` whose product cost is estimated: the stock group sold more units than its recorded purchases left, so those sales take the last average cost. `0` without purchases."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","estimated_sales","total_sales"],"additionalProperties":false},"previous":{"nullable":true,"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false}},"required":["object","cluster","name","product_count","has_activity","amounts","contribution_margin","margin_pct","coverage","previous"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"},"includes_product_cost":{"type":"boolean","description":"Same meaning as on `/v1/pnl/cascade`: `false` on Free/Guru plans, where `cogs`/`product_cost` are always `0` on every row."}},"required":["object","data","has_more","currency","includes_product_cost"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/ads-matrix":{"get":{"description":"Same breakdown as the advertising matrix in the channel card of Rentabilidad: one row per sales connection and ad platform combination (only `amazon_ads` exists today). No `limit`/`offset`, same reasoning as `/v1/pnl/channels`. Same currency-conversion exception as `/v1/pnl/cascade`. Not plan-gated: advertising spend is part of the pre-COGS P&L every plan already sees via `seller_product_metrics`/`vendor_product_metrics`, so there is no `includes_product_cost` field here. A `connection` outside the ones this credential can read comes back as an empty list, not an error.","summary":"Advertising spend per sales connection and ad platform, against that connection's net sales","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_ad_spend"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_platform":{"type":"string","enum":["amazon_ads"]},"amount":{"type":"number","description":"Advertising spend of this connection and platform in the window, negative."},"pct_of_net_sales":{"type":"number","description":"amount / net sales of the connection, as a fraction. `0` when net sales are `0` for the window."},"previous_amount":{"nullable":true,"type":"number"}},"required":["object","connection","ad_platform","amount","pct_of_net_sales","previous_amount"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"}},"required":["object","data","has_more","currency"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/freshness":{"get":{"description":"How complete this P&L is right now: the last day each native source (`amazon_economics`, `amazon_vendor`, `amazon_ads`, `unit_costs`) actually has a row for, inside the requested window. Use it before reading `/v1/pnl/cascade` or `/v1/pnl/products` for a recent period, to tell a real gap from data that has simply not arrived yet - Data Kiosk economics lag 48-72h. No `currency`: nothing here is a monetary amount. `cluster` restricts the freshness check to the products of one or more product clusters. On Free/Guru plans `unit_costs` never appears in `sources` - see `includes_product_cost`. The `unit_costs` date is the last day the cost recalculation processed, which covers every product-day with sales whether or not a cost is loaded: it does not tell you that costs exist (`cost_state` on `/v1/products` does). A `connection` outside the ones this credential can read comes back as an empty `sources` list, not an error. No row for a day can also mean no sales that day: on a low-volume marketplace an old `last_date` is not proof of pending data, and a source with no row inside the window returns no date at all.","summary":"Last day with data per P&L source in the window","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_freshness"]},"includes_product_cost":{"type":"boolean","description":"Whether `unit_costs` can appear in `sources` at all. `false` on Free/Guru plans: the source is omitted from the list entirely, not reported with a `null` date."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["amazon_economics","amazon_vendor","amazon_ads","unit_costs"],"description":"Native source of the line: `amazon_economics` (seller sales/fees from Data Kiosk), `amazon_vendor` (vendor sales), `amazon_ads` (advertising spend) or `unit_costs` (product cost)."},"last_date":{"nullable":true,"description":"Last day with data from this source in the window. `null` when the source has no rows at all in it - not necessarily a problem, e.g. a seller-only account never has `amazon_vendor`.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["source","last_date"],"additionalProperties":false}}},"required":["object","includes_product_cost","sources"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/margin-leaks":{"get":{"description":"Same ranking as the \"Fugas de margen\" screen in Rentabilidad: products whose margin % dropped this period against the previous one of equal length, sorted by `risk_amount` descending - the money actually lost this period at the new margin rate versus the old one, not points. `margin_pct_drop` is `previous_margin_pct - margin_pct`; a product is only ranked once, its drop is always positive. `status` buckets the drop into `leak`/`watch`/`healthy` by the same thresholds as the screen. `status` filters the rows (default all three, like the screen) and `summary` gives the counts per status and the money at risk of the `leak` + `watch` products of the whole ranking in the same call, so there is no need to page through everything to count. `main_cause` is the cost that took the most margin, the same as the \"Main cause\" column of the screen. Only products with net sales in BOTH periods and a drop are returned - a product with no previous net sales (new launch) or an improved margin does not appear. Same currency-conversion exception as `/v1/pnl/cascade`: `currency` is required. `cluster` restricts the ranking to the products of one or more product clusters, same semantics as `/v1/pnl/products`. Paginates with `limit`/`offset`: there is no `order_by`, the ranking order is fixed. An empty list with `has_previous_sales: false` means there is nothing to compare against, not that there are no leaks. Business and Master plans only: Free and Guru get a 403 with `code: \"plan_feature_not_allowed\"`, since without product cost there is no real margin to compare.","summary":"Products ranked by realized margin loss this period vs the previous one","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"search","in":"query","description":"Case-insensitive substring match over the SKU, ASIN or product title, the same as on `/v1/pnl/products`. `summary` and `has_previous_sales` then describe only the matched products.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"status","in":"query","description":"Statuses to list: `leak`, `watch` and/or `healthy`. Default all three, the same as the Rentabilidad screen.","schema":{"anyOf":[{"type":"string","enum":["leak","watch","healthy"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["leak","watch","healthy"]}}]}},{"name":"limit","in":"query","description":"Page size. Paginate with `offset`, not a cursor: these rows are ranked, not records with an id.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_margin_leak"]},"product":{"nullable":true,"description":"FK to `/v1/products`. `null` only if the catalog product was deleted after the sales.","type":"string","pattern":"^[a-f0-9]{24}$"},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"sku":{"type":"string","description":"SKU on Seller, ASIN on Vendor."},"title":{"nullable":true,"type":"string"},"image":{"nullable":true,"type":"string"},"amounts":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false},"previous":{"type":"object","properties":{"categories":{"type":"object","properties":{"sales":{"type":"number"},"refunds":{"type":"number"},"promotions":{"type":"number"},"reimbursements":{"type":"number"},"other_income":{"type":"number"},"commissions":{"type":"number"},"logistics":{"type":"number"},"storage":{"type":"number"},"returns_overheads":{"type":"number"},"other_fees":{"type":"number"},"ads":{"type":"number"},"cogs":{"type":"number"},"own_expenses":{"type":"number"}},"required":["sales","refunds","promotions","reimbursements","other_income","commissions","logistics","storage","returns_overheads","other_fees","ads","cogs","own_expenses"],"additionalProperties":false,"description":"Amount per P&L category (`sales`, `refunds`, `promotions`, `reimbursements`, `other_income`, `commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`, `own_expenses`), signed: revenue positive, costs negative. Net sales (the `revenue` section) are `sales` + `refunds` + `promotions` (customer discounts: coupons, Subscribe & Save, Seller Central promotions, partial shipping discounts; negative) + `reimbursements` (Amazon FBA inventory reimbursements) + `other_income` (shipping charged to the customer). `returns_overheads` are the Amazon refund commission and the FBA return processing fees. `own_expenses` are the account variable own expenses (agency %, packaging per unit...). `cogs` and `own_expenses` are `0` for every row when the caller plan does not include product cost - see `includes_product_cost` at the top of the response."},"sections":{"type":"object","properties":{"revenue":{"type":"number"},"fees_logistics":{"type":"number"},"advertising":{"type":"number"},"product_cost":{"type":"number"},"variable_expenses":{"type":"number"}},"required":["revenue","fees_logistics","advertising","product_cost","variable_expenses"],"additionalProperties":false,"description":"Running subtotals in cascade order: `revenue`, `fees_logistics`, `advertising`, `product_cost`, `variable_expenses`. Each is the sum of its categories, and all five add up to the contribution margin."}},"required":["categories","sections"],"additionalProperties":false},"contribution_margin":{"type":"number","description":"Contribution margin without own expenses, unlike `/v1/pnl/products`: they are decisions of the account, not of the product, so they never explain the leak of one. Neither `amounts` nor `previous` carry them: `variable_expenses` is always 0 here."},"margin_pct":{"type":"number","description":"`contribution_margin` / net sales, before own expenses too."},"previous_margin_pct":{"type":"number"},"margin_pct_drop":{"type":"number","description":"previous_margin_pct minus margin_pct, as a fraction (0.08 = 8 percentage points). Always positive here: rows where margin improved or stayed flat are not leaks."},"risk_amount":{"type":"number","description":"margin_pct_drop × net sales this period: money actually lost this period versus the margin rate of the previous one, not points. Ranking field - rows come sorted by it, descending."},"status":{"type":"string","enum":["leak","watch","healthy"],"description":"`leak` above the high drop threshold, `watch` in the middle band, `healthy` below it. Thresholds are the same ones the Rentabilidad screen uses."},"coverage":{"nullable":true,"description":"Share of this period's sales with a real product cost. Below 100% the margin looks higher than it really is, so the drop may be smaller than shown. A drop inflated by missing cost shows in `previous_coverage`, not here.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"estimated_sales":{"type":"number","description":"Part of `covered_sales` whose product cost is estimated: the stock group sold more units than its recorded purchases left, so those sales take the last average cost. `0` without purchases."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","estimated_sales","total_sales"],"additionalProperties":false},"main_cause":{"nullable":true,"description":"The cost that took the most margin: the one whose share of net sales grew the most versus the previous period. Same rule as the \"Main cause\" column of the screen. `null` when no cost took a noticeable share.","type":"object","properties":{"category":{"type":"string","enum":["commissions","logistics","storage","returns_overheads","other_fees","ads","cogs"]},"margin_pct_drop":{"type":"number","description":"Margin this cost took away, as a fraction (0.05 = 5 percentage points)."}},"required":["category","margin_pct_drop"],"additionalProperties":false},"previous_coverage":{"nullable":true,"description":"Same as `coverage`, for the previous period. If it is lower than `coverage`, the previous margin looked higher than it really was (cost was missing), so part of this drop may come from the cost data, not from the product.","type":"object","properties":{"covered_sales":{"type":"number","description":"Gross sales of the window that have product cost recorded."},"estimated_sales":{"type":"number","description":"Part of `covered_sales` whose product cost is estimated: the stock group sold more units than its recorded purchases left, so those sales take the last average cost. `0` without purchases."},"total_sales":{"type":"number","description":"Gross sales of the whole window."}},"required":["covered_sales","estimated_sales","total_sales"],"additionalProperties":false}},"required":["object","product","connection","country","sku","title","image","amounts","previous","contribution_margin","margin_pct","previous_margin_pct","margin_pct_drop","risk_amount","status","coverage","main_cause","previous_coverage"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"},"summary":{"type":"object","properties":{"leak":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Products in `leak` across the whole ranking, not just this page."},"watch":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Products in `watch` across the whole ranking."},"healthy":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Products in `healthy` across the whole ranking."},"total_risk":{"type":"number","description":"Sum of `risk_amount` of the `leak` and `watch` products, in `currency`: what the screen shows as \"Total at risk\". Ignores `status`, `limit` and `offset`."}},"required":["leak","watch","healthy","total_risk"],"additionalProperties":false,"description":"Counts per status and money at risk (`leak` + `watch` only) of the whole ranking, whatever the page and the `status` filter."},"has_previous_sales":{"type":"boolean","description":"`false` when the previous period has no net sales at all: an empty `data` then means there is nothing to compare against, not that no product lost margin."}},"required":["object","data","has_more","currency","summary","has_previous_sales"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/category-medians":{"get":{"description":"The reference line for a margin-leak breakdown: for each cost category (`commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`; not own expenses, which are decisions of the account, not of the product), the median of `category / net sales` across the products of the account with net sales in the window that have that cost (Vendor has no Amazon fees, products without campaigns have no ads) - a typical catalog rate to compare a leaking product's own breakdown against. Excludes the \"unassigned\" row. No `currency`: each value is a dimensionless fraction, converting amounts would scale numerator and denominator by the same factor and leave it unchanged. `cluster` restricts the catalog the median is computed over to one or more product clusters. Business and Master plans only: Free and Guru get a 403 with `code: \"plan_feature_not_allowed\"`, since without product cost there is no real margin to compare.","summary":"Median of each cost category as a share of net sales, across the account catalog","tags":["pnl"],"parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_category_medians"]},"medians":{"type":"object","properties":{"commissions":{"nullable":true,"type":"number"},"logistics":{"nullable":true,"type":"number"},"storage":{"nullable":true,"type":"number"},"returns_overheads":{"nullable":true,"type":"number"},"other_fees":{"nullable":true,"type":"number"},"ads":{"nullable":true,"type":"number"},"cogs":{"nullable":true,"type":"number"}},"required":["commissions","logistics","storage","returns_overheads","other_fees","ads","cogs"],"additionalProperties":false,"description":"Median of `category / net sales` across the account catalog, one entry per cost category (`commissions`, `logistics`, `storage`, `returns_overheads`, `other_fees`, `ads`, `cogs`; not own expenses, which are decisions of the account, not of the product), counting only the products that have that cost. `null` when no product with net sales has it in the window - never `0`, which would read as \"typically free\"."}},"required":["object","medians"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pnl/inventory":{"get":{"description":"Same data as the \"Inventario\" screen in Rentabilidad: one row per Amazon FBA stock as of today, valued at product cost, with how many days it lasts at the current sales pace, its rotation bucket and its storage fees. Answers \"how much money do I have sitting in Amazon's warehouses, and where is it stuck?\". Amazon Seller FBA only: Vendor stock and the seller's own warehouse are not included. Only products active in Epinium, and stock Epinium has synced from Amazon in the last 7 days. In the EU Amazon pools the stock of every marketplace and reports it repeated in each one, so an EU SKU is ONE row (`region: \"EU\"`) with all its `countries`, never one per country - do not add rows up across countries yourself. No date window: it is today's stock; the sales pace uses the last 90 days of sales and storage the last fully billed month (`storage_month`). `currency` is required and every amount lands in it: product cost at the latest exchange rate, storage at each day's rate. A stock whose product has no product cost has `unit_cost`/`capital` at `null` and is left out of `summary.capital` - see `summary.products_without_cost` before reading a low capital as \"little stock\". Paginates with `limit`/`offset`; `order_by` picks the sort field (default `capital`). `rotation` and `search` filter the rows, never `summary`. A `connection` outside the ones this credential can read comes back as an empty list, not an error. Business and Master plans only: Free and Guru get a 403 with `code: \"plan_feature_not_allowed\"`, since the capital is valued at product cost.","summary":"Today's Amazon FBA stock valued at cost: tied-up capital, coverage and storage","tags":["pnl"],"parameters":[{"name":"currency","in":"query","description":"Target currency for every amount in the response (ISO 4217, e.g. `EUR`). Unlike the rest of the API, this resource converts: a P&L across several marketplaces has to land in one currency to be summed. A day without a rate in `fx_rates_daily` falls back to an approximate rate, it never errors.","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"Keeps the stocks that include this marketplace. A Pan-European stock is shared by every EU country it sells in, so it stays whole, with all its countries - and its sales pace still counts the sales of all of them.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"rotation","in":"query","description":"Rotation buckets to list: `lowStock`, `healthy`, `excess`, `agedRisk` and/or `noSales`. Default all five. Filters the rows only: `summary` always describes the whole scope, so it still tells you how the capital splits across buckets.","schema":{"anyOf":[{"type":"string","enum":["lowStock","healthy","excess","agedRisk","noSales"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["lowStock","healthy","excess","agedRisk","noSales"]}}]}},{"name":"search","in":"query","description":"Case-insensitive substring match over the SKU, ASIN or product title. Filters the rows, not `summary`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","description":"Page size. Paginate with `offset`, not a cursor: these rows are computed from today's stock, not records with an id.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order_by","in":"query","description":"Field to sort by, the camelCase of the row field: `capital` (default), `sellableUnits`, `unitCost`, `coverageDays`, `storageLastMonth`, `storageToSellOut`, `inboundUnits` or `unfulfillableUnits`. Rows with no value for it (no cost, no sales, no storage data) always come last.","schema":{"default":"capital","type":"string","enum":["capital","sellableUnits","unitCost","coverageDays","storageLastMonth","storageToSellOut","inboundUnits","unfulfillableUnits"]}},{"name":"order","in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["pnl_inventory_item"]},"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"FK to `/v1/products`: the catalog product of one of the stock's countries. A Pan-European stock has one product per country; any of them opens the same stock."},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The Amazon Seller connection that owns the stock."},"region":{"type":"string","description":"`EU` for any stock in an EU marketplace (DE, FR, IT, ES, NL, BE, SE, PL, IE), which Amazon pools and reports repeated in each one; otherwise the marketplace code (`GB`, `US`...). With `connection` and `sku` it identifies the stock."},"countries":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"description":"Marketplaces sharing this stock (FKs to `/v1/countries`). One for a non-EU stock."},"sku":{"type":"string"},"asin":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"image":{"nullable":true,"type":"string"},"sellable_units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"In Amazon's warehouse and unsold, including units moving between warehouses or under FC processing. Excludes units reserved for customer orders (`reserved_units`): those are already sold. This is what pays storage and what `capital` values."},"inbound_units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"In inbound shipments to Amazon (created, in transit or being received): they do not pay storage yet."},"unfulfillable_units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Damaged, defective or under investigation by Amazon. Not in `capital`."},"reserved_units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Reserved for customer orders. `sellable_units + reserved_units + inbound_units + unfulfillable_units` is the total quantity Amazon reports for the stock."},"unit_cost":{"nullable":true,"description":"Product cost plus shipping cost per unit, in `currency` at the latest exchange rate available today. `null` when the product has no product cost (shipping alone is not a value) or the cost currency has no exchange rate at all.","type":"number"},"capital":{"nullable":true,"description":"`sellable_units × unit_cost`: money paid and not recovered yet. `null` without `unit_cost`.","type":"number"},"daily_units":{"type":"number","description":"Net units sold per day (sales minus refunds) over its connection's `sales_window`, adding up every country of the stock. A stock that reached Amazon later is measured from its first day in stock."},"coverage_days":{"nullable":true,"description":"`sellable_units / daily_units` in whole days, rounded down: days the stock lasts at the current pace. `null` without sales.","type":"number"},"rotation":{"type":"string","enum":["lowStock","healthy","excess","agedRisk","noSales"],"description":"Bucket by `coverage_days`, not by the units' actual age: `lowStock` under 28 (stock-out risk and Amazon's low-inventory fee), `healthy` under 90, `excess` until the day Amazon's aged inventory surcharge starts, `agedRisk` from that day on (at this pace the last units would still be unsold when it starts). The surcharge starts on day 241 in the EU and the UK and on day 181 in the US (`region: \"US\"`); other marketplaces use the EU day for now, `noSales` without sales."},"storage_last_month":{"nullable":true,"description":"Storage fee Amazon charged for this stock in `storage_month`, positive. `null` when none was charged for it that month.","type":"number"},"storage_per_unit_month":{"nullable":true,"description":"`storage_last_month` divided by the average stock that month: what one unit costs to store per month. `null` without `storage_last_month`, without stock data that month, or when the stock averaged 0 units.","type":"number"},"storage_to_sell_out":{"nullable":true,"description":"Estimated storage until `sellable_units` sell out at `daily_units`, with the higher October-December rate, capped at 12 months. Does not include the aged inventory surcharge. `null` when `storage_per_unit_month` is.","type":"number"},"storage_capped":{"type":"boolean","description":"`true` when the stock does not sell out within 12 months: `storage_to_sell_out` stops there and the real figure is higher."}},"required":["object","product","connection","region","countries","sku","asin","title","image","sellable_units","inbound_units","unfulfillable_units","reserved_units","unit_cost","capital","daily_units","coverage_days","rotation","storage_last_month","storage_per_unit_month","storage_to_sell_out","storage_capped"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"currency":{"type":"string"},"summary":{"type":"object","properties":{"capital":{"type":"number","description":"Sum of `capital` of the whole scope: what the screen shows as \"Capital inmovilizado\". Products without cost are left out."},"capital_by_rotation":{"type":"object","properties":{"lowStock":{"type":"number"},"healthy":{"type":"number"},"excess":{"type":"number"},"agedRisk":{"type":"number"},"noSales":{"type":"number"}},"required":["lowStock","healthy","excess","agedRisk","noSales"],"additionalProperties":false,"description":"`capital` per bucket; adds up to `capital`, give or take a few cents of rounding."},"products":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stocks in scope (rows before `rotation`, `search` and pagination)."},"products_by_rotation":{"type":"object","properties":{"lowStock":{"type":"number"},"healthy":{"type":"number"},"excess":{"type":"number"},"agedRisk":{"type":"number"},"noSales":{"type":"number"}},"required":["lowStock","healthy","excess","agedRisk","noSales"],"additionalProperties":false,"description":"Stocks per bucket, with or without cost."},"products_without_cost":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stocks with no `unit_cost`: their units are not in `capital`."},"products_without_cost_by_rotation":{"type":"object","properties":{"lowStock":{"type":"number"},"healthy":{"type":"number"},"excess":{"type":"number"},"agedRisk":{"type":"number"},"noSales":{"type":"number"}},"required":["lowStock","healthy","excess","agedRisk","noSales"],"additionalProperties":false,"description":"Of `products_by_rotation`, those without cost: explains a bucket with stock and little or no capital."},"units_without_cost":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"`sellable_units` of the stocks without cost."},"storage_last_month":{"nullable":true,"description":"Sum of `storage_last_month`. `null` when no storage was charged in `storage_month` - not zero, unknown.","type":"number"},"storage_to_sell_out":{"nullable":true,"description":"Sum of `storage_to_sell_out`: a floor, since rows without storage data add nothing and `storage_capped` rows only add their first 12 months. `null` when no storage was charged in `storage_month`.","type":"number"}},"required":["capital","capital_by_rotation","products","products_by_rotation","products_without_cost","products_without_cost_by_rotation","units_without_cost","storage_last_month","storage_to_sell_out"],"additionalProperties":false,"description":"Totals of the whole scope (`connection`, `country`, `cluster`), whatever the page, `rotation` and `search`: tied-up capital and its split by rotation bucket, plus storage totals."},"storage_month":{"nullable":true,"description":"YYYY-MM of `storage_last_month`: the last month Amazon has fully billed (it bills storage around the middle of the next month, so before the 20th it is two months back). `null` when no storage was charged in that month.","type":"string"},"sales_window":{"nullable":true,"description":"Days `daily_units` is measured on (YYYY-MM-DD, both included): the 90 days up to the last day with units sold (fewer when the connection's sales history is shorter), never ending more than 14 days ago - a connection that stopped selling is measured with those empty days. Each connection uses its own; this is the most recent. `null` when no connection has sales - every stock is then `noSales`.","type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"required":["object","data","has_more","currency","summary","storage_month","sales_window"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/products/{id}/costs":{"post":{"description":"Same two independent cost timelines as the product ficha and the CSV template: unit cost (COGS) and shipping cost, each with its own effective date. At least one of `price`/`shipping_cost` is required. Writing one does not touch the other - send both to update them together in one call. `404` when `id` does not exist, is not a catalog product (Amazon Seller or Vendor) or falls outside the connections this credential can read. `409` when a recalculation from an earlier cost change on the same connection is still running - retry once it finishes. `409` with code `COST_FROM_PURCHASES` when sending `price` for a product that already has purchases recorded: its unit cost is the weighted average of those purchases, so record or correct a purchase instead. To change its shipping cost, send `shipping_cost` alone, without `price`: with both, the whole request fails and the shipping cost is not saved. Does not accept the CSV bulk-import template; this is the single-product write only.","summary":"Set a product's unit cost and/or shipping cost","tags":["product-costs"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"price":{"description":"New unit cost (COGS), in `currency`. Omit to leave the product's unit cost untouched - `0` sets it to zero, it is not the same as omitting the field.","type":"number","minimum":0},"shipping_cost":{"description":"New shipping cost, in `currency`. Omit to leave the product's shipping cost untouched - `0` sets it to zero, it is not the same as omitting the field.","type":"number","minimum":0},"currency":{"description":"ISO 4217 currency of `price` and `shipping_cost`. Defaults to the product's marketplace currency when omitted.","type":"string","pattern":"^[A-Z]{3}$"},"date":{"description":"Day the new cost(s) start applying from (YYYY-MM-DD). Defaults to today. A date in the past recalculates the margin of periods already closed in `/v1/pnl/*`; a date in the future is rejected with a 400.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["product_cost_write"]},"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"cogs":{"nullable":true,"type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"recalculation":{"type":"string","enum":["queued","not_needed","failed"],"description":"`queued` when `valid_from` is in the past and the recalculation of past periods was enqueued; `not_needed` for a current or absent date; `failed` when the enqueue itself could not be confirmed (the cost was still written - retry the request with the same `price`/`shipping_cost`/`date` and a new idempotency key to try the recalculation again)."}},"required":["unit_cost","currency","valid_from","recalculation"],"additionalProperties":false},"shipping":{"nullable":true,"type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"recalculation":{"type":"string","enum":["queued","not_needed","failed"],"description":"`queued` when `valid_from` is in the past and the recalculation of past periods was enqueued; `not_needed` for a current or absent date; `failed` when the enqueue itself could not be confirmed (the cost was still written - retry the request with the same `price`/`shipping_cost`/`date` and a new idempotency key to try the recalculation again)."}},"required":["unit_cost","currency","valid_from","recalculation"],"additionalProperties":false}},"required":["object","product","cogs","shipping"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/expenses":{"get":{"summary":"List the account's own expenses","tags":["expenses"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"basis","in":"query","description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin.","schema":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"]}},{"name":"status","in":"query","description":"Relative to the current month: `active` (in force), `upcoming` (starts later) or `ended`. Omitted: all.","schema":{"type":"string","enum":["active","upcoming","ended"]}},{"name":"category","in":"query","description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`.","schema":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"concept":{"type":"string"},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"currency":{"nullable":true,"description":"Currency of the amounts of `fixed` and `per_unit` expenses. `null` on percentages.","type":"string"},"frequency":{"nullable":true,"description":"Only `fixed`: `monthly`, `quarterly` and `yearly` amounts are spread over their months; `once` over `spread_months`.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"nullable":true,"type":"number","enum":[1,3,6,12]},"scope":{"type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["connections","countries"],"additionalProperties":false,"description":"Where a variable expense applies. Fixed expenses belong to the whole account and always have it empty."},"amounts":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"amount":{"type":"number"}},"required":["from","amount"],"additionalProperties":false},"description":"Amount in force from each month on, oldest first: changing the amount from a month never touches the earlier ones."},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"valid_to":{"nullable":true,"description":"Last month included. `null`: no end date.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","concept","category","basis","currency","frequency","spread_months","scope","amounts","valid_from","valid_to","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create an own expense","tags":["expenses"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"concept":{"type":"string","minLength":1,"maxLength":120},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"amount":{"type":"number","minimum":0,"maximum":100000000,"description":"In `currency` for `fixed` and `per_unit`; percentage points (5 = 5 %, at most 100) for `pct_net_sales` and `pct_ad_spend`."},"currency":{"description":"Required for `fixed` and `per_unit`; not accepted on percentages.","type":"string","pattern":"^[A-Z]{3}$"},"frequency":{"description":"Required for `fixed`, and only there.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"description":"Only with `basis: fixed` and `frequency: once`: months to spread it over. Omitted: 1.","type":"number","enum":[1,3,6,12]},"scope":{"description":"Only on variable expenses: the sales connections and marketplaces it applies to. Omitted: all.","type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"additionalProperties":false},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"First month it applies to."},"valid_to":{"description":"Last month included. Omitted or `null`: no end date. One-off expenses end at their last spread month at the latest.","nullable":true,"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},"required":["concept","category","basis","amount","valid_from"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"expense":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"concept":{"type":"string"},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"currency":{"nullable":true,"description":"Currency of the amounts of `fixed` and `per_unit` expenses. `null` on percentages.","type":"string"},"frequency":{"nullable":true,"description":"Only `fixed`: `monthly`, `quarterly` and `yearly` amounts are spread over their months; `once` over `spread_months`.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"nullable":true,"type":"number","enum":[1,3,6,12]},"scope":{"type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["connections","countries"],"additionalProperties":false,"description":"Where a variable expense applies. Fixed expenses belong to the whole account and always have it empty."},"amounts":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"amount":{"type":"number"}},"required":["from","amount"],"additionalProperties":false},"description":"Amount in force from each month on, oldest first: changing the amount from a month never touches the earlier ones."},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"valid_to":{"nullable":true,"description":"Last month included. `null`: no end date.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","concept","category","basis","currency","frequency","spread_months","scope","amounts","valid_from","valid_to","created_at","updated_at"],"additionalProperties":false}},"required":["expense"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/expenses/files":{"post":{"description":"Up to 8 MB and 1,000 rows. It only reads and keeps the sheet; nothing is created until `POST /v1/expenses/batch` with its `file_id`. The same file again returns the same `file_id`. Free.","summary":"Upload a spreadsheet of own expenses, kept for 7 days","tags":["expenses"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"File name with its extension: .xlsx, .xls or .csv."},"content_base64":{"type":"string","minLength":1,"maxLength":11184815,"description":"The file, in base64."}},"required":["name","content_base64"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"name":{"type":"string"},"sheet":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"type":"string"}},"required":["file_id","name","sheet","headers","row_count","expires_at"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"summary":"List the expense spreadsheets uploaded in the last 7 days, newest first","tags":["expenses"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string"},"name":{"type":"string"},"sheet":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"type":"string"},"created_at":{"type":"string","description":"When it was uploaded (ISO 8601)."}},"required":["file_id","name","sheet","headers","row_count","expires_at","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/expenses/{id}":{"get":{"tags":["expenses"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"concept":{"type":"string"},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"currency":{"nullable":true,"description":"Currency of the amounts of `fixed` and `per_unit` expenses. `null` on percentages.","type":"string"},"frequency":{"nullable":true,"description":"Only `fixed`: `monthly`, `quarterly` and `yearly` amounts are spread over their months; `once` over `spread_months`.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"nullable":true,"type":"number","enum":[1,3,6,12]},"scope":{"type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["connections","countries"],"additionalProperties":false,"description":"Where a variable expense applies. Fixed expenses belong to the whole account and always have it empty."},"amounts":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"amount":{"type":"number"}},"required":["from","amount"],"additionalProperties":false},"description":"Amount in force from each month on, oldest first: changing the amount from a month never touches the earlier ones."},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"valid_to":{"nullable":true,"description":"Last month included. `null`: no end date.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","concept","category","basis","currency","frequency","spread_months","scope","amounts","valid_from","valid_to","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Rename, recategorize, end or reopen an expense","tags":["expenses"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"concept":{"type":"string","minLength":1,"maxLength":120},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"valid_to":{"description":"Ends the expense after this month, or reopens it with `null`. Ending it deletes the amount changes scheduled after this month, and reopening it does not bring them back.","nullable":true,"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"expense":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"concept":{"type":"string"},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"currency":{"nullable":true,"description":"Currency of the amounts of `fixed` and `per_unit` expenses. `null` on percentages.","type":"string"},"frequency":{"nullable":true,"description":"Only `fixed`: `monthly`, `quarterly` and `yearly` amounts are spread over their months; `once` over `spread_months`.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"nullable":true,"type":"number","enum":[1,3,6,12]},"scope":{"type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["connections","countries"],"additionalProperties":false,"description":"Where a variable expense applies. Fixed expenses belong to the whole account and always have it empty."},"amounts":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"amount":{"type":"number"}},"required":["from","amount"],"additionalProperties":false},"description":"Amount in force from each month on, oldest first: changing the amount from a month never touches the earlier ones."},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"valid_to":{"nullable":true,"description":"Last month included. `null`: no end date.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","concept","category","basis","currency","frequency","spread_months","scope","amounts","valid_from","valid_to","created_at","updated_at"],"additionalProperties":false}},"required":["expense"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete an expense from the whole history","tags":["expenses"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/expenses/batch":{"post":{"description":"Prefer it over creating expenses one by one for more than a few. All or nothing: every expense is checked with the rules of a single create, and if any fails nothing is written and `failure_details` lists each one. Send it first with `dry_run: true` (free, writes nothing), show the result to the person, then again with `dry_run: false`: with every expense, or only the valid ones to create those now (sending only them is what keeps a corrected spreadsheet sent again from duplicating what already went in). `possible_duplicates` warns of rows that match an existing expense or an earlier row, without blocking. Only created expenses are billed. A malformed field (a percentage over 100, a bad month) is a 400 for the whole batch, naming the position.","summary":"Create up to 100 own expenses at once, or check them first","tags":["expenses"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean","description":"Required, no default. `true` checks every expense and writes nothing; `false` creates them all, or none if any fails."},"expenses":{"description":"Up to 100 expenses, each with the same fields as creating one. Send either `expenses` or `file_id`, not both.","minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"concept":{"type":"string","minLength":1,"maxLength":120},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"amount":{"type":"number","minimum":0,"maximum":100000000,"description":"In `currency` for `fixed` and `per_unit`; percentage points (5 = 5 %, at most 100) for `pct_net_sales` and `pct_ad_spend`."},"currency":{"description":"Required for `fixed` and `per_unit`; not accepted on percentages.","type":"string","pattern":"^[A-Z]{3}$"},"frequency":{"description":"Required for `fixed`, and only there.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"description":"Only with `basis: fixed` and `frequency: once`: months to spread it over. Omitted: 1.","type":"number","enum":[1,3,6,12]},"scope":{"description":"Only on variable expenses: the sales connections and marketplaces it applies to. Omitted: all.","type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"additionalProperties":false},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"First month it applies to."},"valid_to":{"description":"Last month included. Omitted or `null`: no end date. One-off expenses end at their last spread month at the latest.","nullable":true,"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},"required":["concept","category","basis","amount","valid_from"],"additionalProperties":false}},"file_id":{"description":"A spreadsheet of expenses uploaded with `POST /v1/expenses/files`, read with the same rules as the import of the Epinium app: columns `concept`, `category`, `type`, `amount`, `currency`, `frequency`, `spread_months`, `valid_from`, `valid_to`, `connection` and `country`. Up to 100 expenses; rows with an error count apart and come back in `failure_details` as `row N`.","type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"description":"With `file_id`: currency (3 letters) for the fixed and per-unit rows WITHOUT one. Without it, those rows fail.","type":"string","pattern":"^[A-Z]{3}$"},"type":{"description":"With `file_id`: how the rows WITHOUT a `type` are calculated, for a spreadsheet with no such column (usually `fixed`). Rows with their own type keep it.","type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"]},"columns":{"description":"With `file_id`: which header of the spreadsheet holds each field, when it is not named like the template. Only the fields you send change. Example: `{ \"concept\": \"Concepto\", \"amount\": \"Importe mensual\" }`.","type":"object","properties":{"concept":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","minLength":1,"maxLength":200},"amount":{"type":"string","minLength":1,"maxLength":200},"currency":{"type":"string","minLength":1,"maxLength":200},"frequency":{"type":"string","minLength":1,"maxLength":200},"spread_months":{"type":"string","minLength":1,"maxLength":200},"valid_from":{"type":"string","minLength":1,"maxLength":200},"valid_to":{"type":"string","minLength":1,"maxLength":200},"connection":{"type":"string","minLength":1,"maxLength":200},"country":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}},"required":["dry_run"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean","description":"`true` when nothing was written: a dry run, or any row that fails, unreadable or rejected by a business rule (all or nothing)."},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Expenses created: all of them, or 0 on a dry run or if any failed."},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failure_details":{"type":"array","items":{"type":"object","properties":{"reference":{"nullable":true,"description":"`expenses[i]`: the position in what you sent, from 0; with `file_id`, `row N`, the row of the spreadsheet.","type":"string"},"error":{"type":"string"}},"required":["reference","error"],"additionalProperties":false},"description":"Every expense that cannot be created, with its reason. Fix them and send the whole batch again."},"possible_duplicates":{"type":"array","items":{"type":"object","properties":{"reference":{"type":"string","description":"`expenses[i]` (with `file_id`, `row N`), the one that looks repeated."},"duplicate_of":{"type":"string","description":"The `id` of an existing expense with the same data, or `expenses[j]` (`row N`) for an earlier one of this batch."}},"required":["reference","duplicate_of"],"additionalProperties":false},"description":"A warning, not an error: same concept, basis, amount, currency, frequency, first month and scope as an existing expense or an earlier one of the batch. Usually the same spreadsheet sent twice; ask the person before creating it. It does not block the batch."},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"concept":{"type":"string"},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"currency":{"nullable":true,"description":"Currency of the amounts of `fixed` and `per_unit` expenses. `null` on percentages.","type":"string"},"frequency":{"nullable":true,"description":"Only `fixed`: `monthly`, `quarterly` and `yearly` amounts are spread over their months; `once` over `spread_months`.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"nullable":true,"type":"number","enum":[1,3,6,12]},"scope":{"type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["connections","countries"],"additionalProperties":false,"description":"Where a variable expense applies. Fixed expenses belong to the whole account and always have it empty."},"amounts":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"amount":{"type":"number"}},"required":["from","amount"],"additionalProperties":false},"description":"Amount in force from each month on, oldest first: changing the amount from a month never touches the earlier ones."},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"valid_to":{"nullable":true,"description":"Last month included. `null`: no end date.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","concept","category","basis","currency","frequency","spread_months","scope","amounts","valid_from","valid_to","created_at","updated_at"],"additionalProperties":false},"description":"The created expenses, in the order sent. Empty on a dry run or if any failed."},"to_create":{"type":"array","items":{"type":"object","properties":{"concept":{"type":"string"},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"currency":{"nullable":true,"description":"Currency of the amounts of `fixed` and `per_unit` expenses. `null` on percentages.","type":"string"},"frequency":{"nullable":true,"description":"Only `fixed`: `monthly`, `quarterly` and `yearly` amounts are spread over their months; `once` over `spread_months`.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"nullable":true,"type":"number","enum":[1,3,6,12]},"scope":{"type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["connections","countries"],"additionalProperties":false,"description":"Where a variable expense applies. Fixed expenses belong to the whole account and always have it empty."},"amounts":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"amount":{"type":"number"}},"required":["from","amount"],"additionalProperties":false},"description":"Amount in force from each month on, oldest first: changing the amount from a month never touches the earlier ones."},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"valid_to":{"nullable":true,"description":"Last month included. `null`: no end date.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"reference":{"type":"string","description":"`expenses[i]`, or `row N` with `file_id`."}},"required":["concept","category","basis","currency","frequency","spread_months","scope","amounts","valid_from","valid_to","reference"],"additionalProperties":false},"description":"Only when nothing was written: every expense that passes, as it would be created, in the order sent. Show them to the person before creating them (concept, how it is computed, amount, frequency, months): it is how they check that each value, above all the type and the amount, was read as they meant. Empty once they are created."},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credits of the expenses created, or on a dry run, of creating the ones in `to_create`. The dry run itself is free."}},"required":["dry_run","created","failed","failure_details","possible_duplicates","expenses","to_create","credits"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/expenses/{id}/amounts":{"post":{"summary":"Change the amount of an expense from a month on","tags":["expenses"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"Month the new amount applies from. Earlier months keep theirs; later changes are replaced by this one. One-off expenses only change as a whole: use their `valid_from`."},"amount":{"type":"number","minimum":0,"maximum":100000000,"description":"In the expense currency, or percentage points (at most 100) on percentages."}},"required":["from","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"expense":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"concept":{"type":"string"},"category":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"A standard category key (`staff`, `agency`, `software`, `logistics`, `off_amazon_marketing`, `content`, `legal`, `insurance`, `other`) or the `id` of one of the account categories from `/v1/expense-categories`."},"basis":{"type":"string","enum":["fixed","per_unit","pct_net_sales","pct_ad_spend"],"description":"How the expense is computed. `fixed`: an amount per period, subtracted after contribution margin and only on the whole-account P&L. `per_unit`: an amount per net unit sold. `pct_net_sales`: a percentage of net sales. `pct_ad_spend`: a percentage of advertising spend. The three variable ones are subtracted per product and day, before contribution margin."},"currency":{"nullable":true,"description":"Currency of the amounts of `fixed` and `per_unit` expenses. `null` on percentages.","type":"string"},"frequency":{"nullable":true,"description":"Only `fixed`: `monthly`, `quarterly` and `yearly` amounts are spread over their months; `once` over `spread_months`.","type":"string","enum":["once","monthly","quarterly","yearly"]},"spread_months":{"nullable":true,"type":"number","enum":[1,3,6,12]},"scope":{"type":"object","properties":{"connections":{"default":[],"description":"Sales connections it applies to. Empty: every sales connection of the account.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"countries":{"default":[],"description":"Marketplaces it applies to. Empty: every marketplace.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["connections","countries"],"additionalProperties":false,"description":"Where a variable expense applies. Fixed expenses belong to the whole account and always have it empty."},"amounts":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"amount":{"type":"number"}},"required":["from","amount"],"additionalProperties":false},"description":"Amount in force from each month on, oldest first: changing the amount from a month never touches the earlier ones."},"valid_from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"valid_to":{"nullable":true,"description":"Last month included. `null`: no end date.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","concept","category","basis","currency","frequency","spread_months","scope","amounts","valid_from","valid_to","created_at","updated_at"],"additionalProperties":false}},"required":["expense"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/expense-categories":{"get":{"summary":"List the expense categories: standard ones and the account ones","tags":["expense-categories"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"What goes in `category` of an expense: the key of a standard category or the id of an account one."},"name":{"type":"string","description":"The account category name, or the key itself on standard ones."},"standard":{"type":"boolean","description":"Standard categories come with the platform and cannot be renamed or deleted."}},"required":["id","name","standard"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create an account expense category","tags":["expense-categories"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"What goes in `category` of an expense: the key of a standard category or the id of an account one."},"name":{"type":"string","description":"The account category name, or the key itself on standard ones."},"standard":{"type":"boolean","description":"Standard categories come with the platform and cannot be renamed or deleted."}},"required":["id","name","standard"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/expense-categories/{id}":{"patch":{"summary":"Rename an account expense category","tags":["expense-categories"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","enum":["staff","agency","software","logistics","off_amazon_marketing","content","legal","insurance","other"]},{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}],"description":"What goes in `category` of an expense: the key of a standard category or the id of an account one."},"name":{"type":"string","description":"The account category name, or the key itself on standard ones."},"standard":{"type":"boolean","description":"Standard categories come with the platform and cannot be renamed or deleted."}},"required":["id","name","standard"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete an account expense category that no expense uses","tags":["expense-categories"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/products/{id}/purchases":{"post":{"description":"The same as recording a purchase in the product ficha: the product's unit cost becomes the weighted average of its stock, for every product of its stock group, from the purchase day. The first purchase creates the group with the products that share the stock; if they have different costs today, `prior_stock_unit_cost` is required (`400` with code `PRIOR_STOCK_VALUE_REQUIRED`). `400` with `STOCK_ON_HAND_UNKNOWN` when `stock_on_hand` is omitted and there is no Amazon FBA inventory for those days. Vendor products have no purchases: the stock belongs to Amazon. Changing a purchase recalculates its average cost and every later one in the group, and the margin of past periods: `409` with code `UNIT_COSTS_RECALCULATION_IN_PROGRESS` while an earlier recalculation of one of the group's connections is still running (retry once it finishes), `409` with `STOCK_GROUP_BUSY` while another change is being saved on the same stock (retry in a few seconds). Reading and writing purchases needs a plan that includes product cost (Business or Master): `403` otherwise. With a stock group spread over several connections, reading needs access to one of them and writing to all: correcting or deleting a purchase out of reach is a `404`, and recording one in such a group a `400` with code `STOCK_GROUP_OUT_OF_SCOPE`.","summary":"Record a purchase of a product","tags":["product-purchases"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"description":"Day of the purchase. Defaults to today; a future day is rejected.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"units":{"type":"integer","minimum":1,"maximum":9007199254740991},"cost_elements":{"minItems":1,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","inbound_shipping","tariff","other"],"description":"`product` is what the supplier charges per unit; `inbound_shipping` (shipping to the Amazon warehouse), `tariff` and `other` add to it. Shipping to the customer is not a purchase cost: it is the product shipping cost of `POST /v1/products/:id/costs`."},"amount":{"type":"number","minimum":0,"description":"Per unit, in `currency`."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["type","amount","currency"],"additionalProperties":false},"description":"At least the `product` cost. All amounts per unit."},"stock_on_hand":{"description":"Units in stock right before the purchase. Omit it to use the last Amazon FBA inventory of the 7 days before, plus the purchases of the group recorded since then; FBM products have no FBA inventory, so it is required there.","type":"integer","minimum":0,"maximum":9007199254740991},"prior_stock_unit_cost":{"description":"Value per unit of the stock already there, in the stock group currency: for the first purchase, the group takes the purchase currency. Only needed for the first purchase of a stock shared by products with different costs (see `GET /v1/products/:id/stock-group`); otherwise the cost in force that day is used.","type":"number","minimum":0},"reference":{"type":"string","minLength":1,"maxLength":100,"description":"Purchase order number. Unique within the stock group: the same reference again is rejected with `409` `DUPLICATE_PURCHASE_EXTERNAL_ID`, so a retried request never duplicates the purchase."}},"required":["units","cost_elements"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["purchase_change"]},"purchase":{"type":"object","properties":{"object":{"type":"string","enum":["purchase"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"stock_group":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Stock group the purchase belongs to: the products that share the same physical stock (on Amazon pan-EU, the same SKU in every EU country). A purchase changes the cost of all of them."},"connections":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cost_elements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","inbound_shipping","tariff","other"],"description":"`product` is what the supplier charges per unit; `inbound_shipping` (shipping to the Amazon warehouse), `tariff` and `other` add to it. Shipping to the customer is not a purchase cost: it is the product shipping cost of `POST /v1/products/:id/costs`."},"amount":{"type":"number","minimum":0,"description":"Per unit, in `currency`."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["type","amount","currency"],"additionalProperties":false}},"stock_on_hand":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units in stock right before the purchase, without what was on its way."},"stock_on_hand_origin":{"type":"string","enum":["fba","user"],"description":"`fba` when taken from Amazon FBA inventory, `user` when given by the user."},"prior_stock_unit_cost":{"nullable":true,"description":"Value per unit, in the group `currency`, given to the stock that was there before the purchase. `null` when it came from the cost in force that day.","type":"number"},"resulting_avg_cost":{"type":"number","description":"Weighted average unit cost after this purchase, in the group `currency`."},"currency":{"type":"string","description":"The stock group's currency: the one the average is calculated in."},"origin":{"type":"string","enum":["manual","csv","api","erp"]},"reference":{"nullable":true,"description":"Purchase order number. Unique within the stock group.","type":"string"},"created_at":{"type":"string"}},"required":["object","id","stock_group","connections","date","units","cost_elements","stock_on_hand","stock_on_hand_origin","prior_stock_unit_cost","resulting_avg_cost","currency","origin","reference","created_at"],"additionalProperties":false},"stock_group":{"type":"object","properties":{"object":{"type":"string","enum":["stock_group"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"currency":{"type":"string"},"members":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"sku":{"type":"string"}},"required":["product","connection","country","sku"],"additionalProperties":false}}},"required":["object","id","currency","members"],"additionalProperties":false},"recalculation":{"type":"string","enum":["queued","not_needed","failed"],"description":"`queued` when the margin of past periods is being recalculated with the new cost; `failed` when that could not be confirmed (the purchase was still saved)."}},"required":["object","purchase","stock_group","recalculation"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/purchases":{"get":{"description":"In the order they were recorded. To answer \"how much did I buy this month\", filter by `from`/`to`. Reading and writing purchases needs a plan that includes product cost (Business or Master): `403` otherwise.","summary":"Purchases of the account, by connection and dates","tags":["product-purchases"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"connection","in":"query","description":"Only purchases of stock groups with products in this connection.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"from","in":"query","description":"First purchase day, inclusive.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","description":"Last purchase day, inclusive.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["purchase"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"stock_group":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Stock group the purchase belongs to: the products that share the same physical stock (on Amazon pan-EU, the same SKU in every EU country). A purchase changes the cost of all of them."},"connections":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cost_elements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","inbound_shipping","tariff","other"],"description":"`product` is what the supplier charges per unit; `inbound_shipping` (shipping to the Amazon warehouse), `tariff` and `other` add to it. Shipping to the customer is not a purchase cost: it is the product shipping cost of `POST /v1/products/:id/costs`."},"amount":{"type":"number","minimum":0,"description":"Per unit, in `currency`."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["type","amount","currency"],"additionalProperties":false}},"stock_on_hand":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units in stock right before the purchase, without what was on its way."},"stock_on_hand_origin":{"type":"string","enum":["fba","user"],"description":"`fba` when taken from Amazon FBA inventory, `user` when given by the user."},"prior_stock_unit_cost":{"nullable":true,"description":"Value per unit, in the group `currency`, given to the stock that was there before the purchase. `null` when it came from the cost in force that day.","type":"number"},"resulting_avg_cost":{"type":"number","description":"Weighted average unit cost after this purchase, in the group `currency`."},"currency":{"type":"string","description":"The stock group's currency: the one the average is calculated in."},"origin":{"type":"string","enum":["manual","csv","api","erp"]},"reference":{"nullable":true,"description":"Purchase order number. Unique within the stock group.","type":"string"},"created_at":{"type":"string"}},"required":["object","id","stock_group","connections","date","units","cost_elements","stock_on_hand","stock_on_hand_origin","prior_stock_unit_cost","resulting_avg_cost","currency","origin","reference","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/purchases/{id}":{"patch":{"description":"Send only what changes. Moving the `date` of a purchase whose stock came from Amazon FBA takes the FBA stock of the new day. Changing a purchase recalculates its average cost and every later one in the group, and the margin of past periods: `409` with code `UNIT_COSTS_RECALCULATION_IN_PROGRESS` while an earlier recalculation of one of the group's connections is still running (retry once it finishes), `409` with `STOCK_GROUP_BUSY` while another change is being saved on the same stock (retry in a few seconds). Reading and writing purchases needs a plan that includes product cost (Business or Master): `403` otherwise. With a stock group spread over several connections, reading needs access to one of them and writing to all: correcting or deleting a purchase out of reach is a `404`, and recording one in such a group a `400` with code `STOCK_GROUP_OUT_OF_SCOPE`.","summary":"Correct a purchase","tags":["product-purchases"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"units":{"type":"integer","minimum":1,"maximum":9007199254740991},"cost_elements":{"minItems":1,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","inbound_shipping","tariff","other"],"description":"`product` is what the supplier charges per unit; `inbound_shipping` (shipping to the Amazon warehouse), `tariff` and `other` add to it. Shipping to the customer is not a purchase cost: it is the product shipping cost of `POST /v1/products/:id/costs`."},"amount":{"type":"number","minimum":0,"description":"Per unit, in `currency`."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["type","amount","currency"],"additionalProperties":false}},"stock_on_hand":{"description":"`null` takes it from Amazon FBA again.","nullable":true,"type":"integer","minimum":0,"maximum":9007199254740991},"prior_stock_unit_cost":{"nullable":true,"type":"number","minimum":0},"reference":{"nullable":true,"type":"string","minLength":1,"maxLength":100,"description":"Purchase order number. Unique within the stock group: the same reference again is rejected with `409` `DUPLICATE_PURCHASE_EXTERNAL_ID`, so a retried request never duplicates the purchase."}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["purchase_change"]},"purchase":{"type":"object","properties":{"object":{"type":"string","enum":["purchase"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"stock_group":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Stock group the purchase belongs to: the products that share the same physical stock (on Amazon pan-EU, the same SKU in every EU country). A purchase changes the cost of all of them."},"connections":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cost_elements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","inbound_shipping","tariff","other"],"description":"`product` is what the supplier charges per unit; `inbound_shipping` (shipping to the Amazon warehouse), `tariff` and `other` add to it. Shipping to the customer is not a purchase cost: it is the product shipping cost of `POST /v1/products/:id/costs`."},"amount":{"type":"number","minimum":0,"description":"Per unit, in `currency`."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["type","amount","currency"],"additionalProperties":false}},"stock_on_hand":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units in stock right before the purchase, without what was on its way."},"stock_on_hand_origin":{"type":"string","enum":["fba","user"],"description":"`fba` when taken from Amazon FBA inventory, `user` when given by the user."},"prior_stock_unit_cost":{"nullable":true,"description":"Value per unit, in the group `currency`, given to the stock that was there before the purchase. `null` when it came from the cost in force that day.","type":"number"},"resulting_avg_cost":{"type":"number","description":"Weighted average unit cost after this purchase, in the group `currency`."},"currency":{"type":"string","description":"The stock group's currency: the one the average is calculated in."},"origin":{"type":"string","enum":["manual","csv","api","erp"]},"reference":{"nullable":true,"description":"Purchase order number. Unique within the stock group.","type":"string"},"created_at":{"type":"string"}},"required":["object","id","stock_group","connections","date","units","cost_elements","stock_on_hand","stock_on_hand_origin","prior_stock_unit_cost","resulting_avg_cost","currency","origin","reference","created_at"],"additionalProperties":false},"stock_group":{"type":"object","properties":{"object":{"type":"string","enum":["stock_group"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"currency":{"type":"string"},"members":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"sku":{"type":"string"}},"required":["product","connection","country","sku"],"additionalProperties":false}}},"required":["object","id","currency","members"],"additionalProperties":false},"recalculation":{"type":"string","enum":["queued","not_needed","failed"],"description":"`queued` when the margin of past periods is being recalculated with the new cost; `failed` when that could not be confirmed (the purchase was still saved)."}},"required":["object","purchase","stock_group","recalculation"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"It cannot be undone. The average cost is recalculated without it; deleting the last purchase of a group dissolves it, and the costs recorded before it apply again. Changing a purchase recalculates its average cost and every later one in the group, and the margin of past periods: `409` with code `UNIT_COSTS_RECALCULATION_IN_PROGRESS` while an earlier recalculation of one of the group's connections is still running (retry once it finishes), `409` with `STOCK_GROUP_BUSY` while another change is being saved on the same stock (retry in a few seconds). Reading and writing purchases needs a plan that includes product cost (Business or Master): `403` otherwise. With a stock group spread over several connections, reading needs access to one of them and writing to all: correcting or deleting a purchase out of reach is a `404`, and recording one in such a group a `400` with code `STOCK_GROUP_OUT_OF_SCOPE`.","summary":"Delete a purchase","tags":["product-purchases"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["purchase_change"]},"purchase":{"type":"object","properties":{"object":{"type":"string","enum":["purchase"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"stock_group":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Stock group the purchase belongs to: the products that share the same physical stock (on Amazon pan-EU, the same SKU in every EU country). A purchase changes the cost of all of them."},"connections":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cost_elements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","inbound_shipping","tariff","other"],"description":"`product` is what the supplier charges per unit; `inbound_shipping` (shipping to the Amazon warehouse), `tariff` and `other` add to it. Shipping to the customer is not a purchase cost: it is the product shipping cost of `POST /v1/products/:id/costs`."},"amount":{"type":"number","minimum":0,"description":"Per unit, in `currency`."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["type","amount","currency"],"additionalProperties":false}},"stock_on_hand":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Units in stock right before the purchase, without what was on its way."},"stock_on_hand_origin":{"type":"string","enum":["fba","user"],"description":"`fba` when taken from Amazon FBA inventory, `user` when given by the user."},"prior_stock_unit_cost":{"nullable":true,"description":"Value per unit, in the group `currency`, given to the stock that was there before the purchase. `null` when it came from the cost in force that day.","type":"number"},"resulting_avg_cost":{"type":"number","description":"Weighted average unit cost after this purchase, in the group `currency`."},"currency":{"type":"string","description":"The stock group's currency: the one the average is calculated in."},"origin":{"type":"string","enum":["manual","csv","api","erp"]},"reference":{"nullable":true,"description":"Purchase order number. Unique within the stock group.","type":"string"},"created_at":{"type":"string"}},"required":["object","id","stock_group","connections","date","units","cost_elements","stock_on_hand","stock_on_hand_origin","prior_stock_unit_cost","resulting_avg_cost","currency","origin","reference","created_at"],"additionalProperties":false},"stock_group":{"type":"object","properties":{"object":{"type":"string","enum":["stock_group"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"currency":{"type":"string"},"members":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"sku":{"type":"string"}},"required":["product","connection","country","sku"],"additionalProperties":false}}},"required":["object","id","currency","members"],"additionalProperties":false},"recalculation":{"type":"string","enum":["queued","not_needed","failed"],"description":"`queued` when the margin of past periods is being recalculated with the new cost; `failed` when that could not be confirmed (the purchase was still saved)."}},"required":["object","purchase","stock_group","recalculation"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/products/{id}/stock-group":{"get":{"description":"Products that share the same physical stock (on Amazon pan-EU, the same SKU in every EU country; UK and Vendor go apart) share one average cost. A group is created by the first purchase: before it, `proposed_members` says who it would join and `costs_differ` whether that first purchase needs `prior_stock_unit_cost`. Reading and writing purchases needs a plan that includes product cost (Business or Master): `403` otherwise.","summary":"The stock group of a product, or who its first purchase would join","tags":["product-purchases"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["product_stock_group"]},"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"stock_group":{"nullable":true,"description":"`null` until the first purchase of the product: groups are created by it.","type":"object","properties":{"object":{"type":"string","enum":["stock_group"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"currency":{"type":"string"},"members":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"sku":{"type":"string"}},"required":["product","connection","country","sku"],"additionalProperties":false}}},"required":["object","id","currency","members"],"additionalProperties":false},"proposed_members":{"nullable":true,"description":"Without a group yet: the products its first purchase would join because they share its stock, itself included. `null` when it would go alone.","type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"sku":{"type":"string"},"current_cost":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["amount","currency","valid_from"],"additionalProperties":false}},"required":["product","connection","country","sku","current_cost"],"additionalProperties":false}},"costs_differ":{"type":"boolean","description":"Without a group: the proposed products have different costs today, so the first purchase must say what the existing stock was worth (`prior_stock_unit_cost`)."}},"required":["object","product","stock_group","proposed_members","costs_differ"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/cost-imports/files":{"post":{"description":"Up to 8 MB and 200,000 rows: a whole catalog fits in one file. It only reads and keeps the sheet; nothing is imported until `POST /v1/cost-imports` with its `file_id`. The same file again returns the same `file_id`. Free.","summary":"Upload a spreadsheet of product costs, kept for 7 days","tags":["cost-imports"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"File name with its extension: .xlsx, .xls or .csv."},"content_base64":{"type":"string","minLength":1,"maxLength":11184815,"description":"The file, in base64."}},"required":["name","content_base64"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"name":{"type":"string"},"sheet":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"type":"string"}},"required":["file_id","name","sheet","headers","row_count","expires_at"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"summary":"List the cost spreadsheets uploaded in the last 7 days, newest first","tags":["cost-imports"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string"},"name":{"type":"string"},"sheet":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"type":"string"},"created_at":{"type":"string","description":"When it was uploaded (ISO 8601)."}},"required":["file_id","name","sheet","headers","row_count","expires_at","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/cost-imports/preview":{"post":{"description":"Same body as `POST /v1/cost-imports`, and the same rules row by row, but nothing is saved or charged: it says how many rows would be applied, skipped and rejected (and why, with examples), how many go without a date and what the import would cost. Free. A row can still be rejected when applied if there is no exchange rate for its currency on its date.","summary":"Check a cost import without saving anything","tags":["cost-imports"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Amazon Seller or Vendor connection the costs belong to (from `epinium_list_connections`). One import is one connection; a `marketplace` column picks the country inside it, and without it each row applies to every country where the SKU exists."},"kind":{"description":"`costs` (default): fixed unit and shipping costs per product and date. `purchases`: purchases from suppliers, one per row - each one makes the unit cost the weighted average of the stock, for every product sharing that stock (Seller only). The same templates as the cost import of the Epinium app.","type":"string","enum":["costs","purchases"]},"file_ids":{"description":"Cost spreadsheets uploaded with `POST /v1/cost-imports/files` (`file_id` of each); a file uploaded for listing changes is not accepted. One file is enough for a whole catalog: up to 200,000 rows per import. Up to 10 files are applied as ONE import with a single recalculation. Send either `file_ids` or `headers` + `rows`, not both.","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"headers":{"description":"Column names of `rows`, when there is no uploaded file. Costs template: `sellerSku` (the ASIN on Vendor), `marketplace`, `date`, `cogs`, `cogsCurrency`, `shippingCost`, `shippingCostCurrency`. Purchases template: `sellerSku`, `marketplace`, `date`, `units`, `currency`, `productCost`, `inboundShippingCost`, `tariffCost`, `otherCost`, `stockOnHand`, `reference`. Common names like \"sku\", \"coste\", \"unidades\" or \"fecha\" are recognised too.","minItems":1,"maxItems":250,"type":"array","items":{"type":"string","maxLength":200}},"rows":{"description":"One array per product, values in the order of `headers`, exactly as in the file.","minItems":1,"maxItems":5000,"type":"array","items":{"maxItems":250,"type":"array","items":{"anyOf":[{"type":"string","maxLength":10000},{"type":"number"},{"type":"boolean"},{"type":"string","nullable":true,"enum":[null]}]}}},"date":{"description":"Day (YYYY-MM-DD) the costs of the rows WITHOUT a `date` start applying from. Rows with their own date keep it. Without it, a row with no date starts today and does not cover earlier sales. A future date is rejected per row.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"columns":{"description":"Which header of the file holds each field, when the automatic matching does not find it - the \"Columns\" step of the app. Only the fields you send change; the rest are still matched by name. Example: `{ \"sellerSku\": \"Referencia ERP\", \"cogs\": \"Precio neto\" }`.","type":"object","properties":{"sellerSku":{"type":"string","minLength":1,"maxLength":200},"marketplace":{"type":"string","minLength":1,"maxLength":200},"date":{"type":"string","minLength":1,"maxLength":200},"cogsCurrency":{"type":"string","minLength":1,"maxLength":200},"cogs":{"type":"string","minLength":1,"maxLength":200},"shippingCostCurrency":{"type":"string","minLength":1,"maxLength":200},"shippingCost":{"type":"string","minLength":1,"maxLength":200},"units":{"type":"string","minLength":1,"maxLength":200},"currency":{"type":"string","minLength":1,"maxLength":200},"productCost":{"type":"string","minLength":1,"maxLength":200},"inboundShippingCost":{"type":"string","minLength":1,"maxLength":200},"tariffCost":{"type":"string","minLength":1,"maxLength":200},"otherCost":{"type":"string","minLength":1,"maxLength":200},"stockOnHand":{"type":"string","minLength":1,"maxLength":200},"reference":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"name":{"description":"Name shown in the import history of the Epinium app. Defaults to the uploaded file name.","type":"string","maxLength":200}},"required":["connection"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["cost_import_preview"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"checks":{"type":"string","enum":["catalog","format"],"description":"`catalog`: every row was matched against the products and costs of the connection, as when applying. `format` (purchases): the rows were only checked for format; the SKU, its stock group and the stock before each purchase are checked when applying, so some rows can still be rejected then."},"total_rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows that would be sent to the import (empty rows and `not_sent` excluded)."},"will_apply":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows that match a product and would change its cost."},"skipped":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows that change nothing and cost nothing: without any amount, or already the cost in place on their date (see `unchanged`)."},"unchanged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Of `skipped`, rows whose amounts are already the cost in place on their date, in every product they match. An amount without currency is compared in the marketplace currency."},"rejected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rejected_by_reason":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["missing_sku","invalid_amount","invalid_currency","invalid_date","future_date","currency_required","ambiguous_amount","sku_not_found","outside_whitelist","marketplace_not_found","missing_exchange_rate","missing_marketplace_currency","invalid_unit_cost","future_cost","stock_group_out_of_scope","invalid_units","invalid_stock_on_hand","stock_on_hand_unknown","marketplace_required","not_client_stock","cost_from_purchases","duplicate_reference","prior_stock_value_required","parent_product"]},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["reason","rows"],"additionalProperties":false},"description":"How many rows would be rejected for each reason, most frequent first."},"rejected_rows":{"type":"array","items":{"type":"object","properties":{"file_index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Position of the row's file in the `file_ids` that created the import, from 0; `0` when the rows came in the request."},"row":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Row of the file as the user sees it (the header is row 1)."},"sku":{"type":"string"},"marketplace":{"nullable":true,"type":"string"},"reason":{"type":"string","enum":["missing_sku","invalid_amount","invalid_currency","invalid_date","future_date","currency_required","ambiguous_amount","sku_not_found","outside_whitelist","marketplace_not_found","missing_exchange_rate","missing_marketplace_currency","invalid_unit_cost","future_cost","stock_group_out_of_scope","invalid_units","invalid_stock_on_hand","stock_on_hand_unknown","marketplace_required","not_client_stock","cost_from_purchases","duplicate_reference","prior_stock_value_required","parent_product"]}},"required":["file_index","row","sku","marketplace","reason"],"additionalProperties":false},"description":"Up to 50 rejected rows as examples, in file order."},"without_date":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows that would be applied with no date, so their cost starts today and does not cover earlier sales. Pass `date` to give them one."},"shadowed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows that would be applied with a date earlier than a cost the product already has: each cost counts from its date until the next one, so these only count until that later cost, which is kept. Tell the user, with `shadowed_rows`."},"shadowed_rows":{"type":"array","items":{"type":"object","properties":{"file_index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Position of the row's file in the `file_ids` that created the import, from 0; `0` when the rows came in the request."},"row":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Row of the file as the user sees it (the header is row 1)."},"sku":{"type":"string"},"marketplace":{"nullable":true,"type":"string"},"next_cost_from":{"type":"string","description":"Date (YYYY-MM-DD) of the existing cost that takes over: the row counts until the day before."}},"required":["file_index","row","sku","marketplace","next_cost_from"],"additionalProperties":false},"description":"Up to 50 of the `shadowed` rows as examples, in file order."},"products":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Products whose cost would change: a row without marketplace goes to every country of the SKU, and a Vendor ASIN to all its vendor codes."},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What the import would cost: one `api:productCost:write` per row in `will_apply`."},"not_sent":{"type":"array","items":{"type":"object","properties":{"file_index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Position of the row's file in the `file_ids` that created the import, from 0; `0` when the rows came in the request."},"row":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Row of the file as the user sees it (the header is row 1)."},"sku":{"type":"string"},"reason":{"type":"string","enum":["cell_too_long"]},"column":{"type":"string"}},"required":["file_index","row","sku","reason","column"],"additionalProperties":false},"description":"Rows that would be left out because a cell is longer than the template allows. Up to 50, in file order; `not_sent_total` has how many there are."},"not_sent_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many rows were left out, `not_sent` included."}},"required":["object","connection","checks","total_rows","will_apply","skipped","unchanged","rejected","rejected_by_reason","rejected_rows","without_date","shadowed","shadowed_rows","products","credits","not_sent","not_sent_total"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/cost-imports":{"post":{"description":"Same template and rules as the cost import of the Epinium app: each row sets the unit cost (COGS) and/or shipping cost of one SKU from its `date`. Rows are applied in the background with ONE recalculation of the margin at the end; follow `GET /v1/cost-imports/:id` until `status` is `finished`, `finished_with_errors` or `error`. `400` when no column can be read as the SKU or as an amount, or without a marketplace column and no currency columns. `409` while a recalculation from an earlier cost change is still running on the connection. Each applied row is charged like `POST /v1/products/:id/costs`: the rows that can be applied are reserved on creation (`402` and nothing imported if the balance is short) and, when it finishes, only the applied ones are charged and the rest is returned.","summary":"Import the costs of many products from a spreadsheet","tags":["cost-imports"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Amazon Seller or Vendor connection the costs belong to (from `epinium_list_connections`). One import is one connection; a `marketplace` column picks the country inside it, and without it each row applies to every country where the SKU exists."},"kind":{"description":"`costs` (default): fixed unit and shipping costs per product and date. `purchases`: purchases from suppliers, one per row - each one makes the unit cost the weighted average of the stock, for every product sharing that stock (Seller only). The same templates as the cost import of the Epinium app.","type":"string","enum":["costs","purchases"]},"file_ids":{"description":"Cost spreadsheets uploaded with `POST /v1/cost-imports/files` (`file_id` of each); a file uploaded for listing changes is not accepted. One file is enough for a whole catalog: up to 200,000 rows per import. Up to 10 files are applied as ONE import with a single recalculation. Send either `file_ids` or `headers` + `rows`, not both.","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"headers":{"description":"Column names of `rows`, when there is no uploaded file. Costs template: `sellerSku` (the ASIN on Vendor), `marketplace`, `date`, `cogs`, `cogsCurrency`, `shippingCost`, `shippingCostCurrency`. Purchases template: `sellerSku`, `marketplace`, `date`, `units`, `currency`, `productCost`, `inboundShippingCost`, `tariffCost`, `otherCost`, `stockOnHand`, `reference`. Common names like \"sku\", \"coste\", \"unidades\" or \"fecha\" are recognised too.","minItems":1,"maxItems":250,"type":"array","items":{"type":"string","maxLength":200}},"rows":{"description":"One array per product, values in the order of `headers`, exactly as in the file.","minItems":1,"maxItems":5000,"type":"array","items":{"maxItems":250,"type":"array","items":{"anyOf":[{"type":"string","maxLength":10000},{"type":"number"},{"type":"boolean"},{"type":"string","nullable":true,"enum":[null]}]}}},"date":{"description":"Day (YYYY-MM-DD) the costs of the rows WITHOUT a `date` start applying from. Rows with their own date keep it. Without it, a row with no date starts today and does not cover earlier sales. A future date is rejected per row.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"columns":{"description":"Which header of the file holds each field, when the automatic matching does not find it - the \"Columns\" step of the app. Only the fields you send change; the rest are still matched by name. Example: `{ \"sellerSku\": \"Referencia ERP\", \"cogs\": \"Precio neto\" }`.","type":"object","properties":{"sellerSku":{"type":"string","minLength":1,"maxLength":200},"marketplace":{"type":"string","minLength":1,"maxLength":200},"date":{"type":"string","minLength":1,"maxLength":200},"cogsCurrency":{"type":"string","minLength":1,"maxLength":200},"cogs":{"type":"string","minLength":1,"maxLength":200},"shippingCostCurrency":{"type":"string","minLength":1,"maxLength":200},"shippingCost":{"type":"string","minLength":1,"maxLength":200},"units":{"type":"string","minLength":1,"maxLength":200},"currency":{"type":"string","minLength":1,"maxLength":200},"productCost":{"type":"string","minLength":1,"maxLength":200},"inboundShippingCost":{"type":"string","minLength":1,"maxLength":200},"tariffCost":{"type":"string","minLength":1,"maxLength":200},"otherCost":{"type":"string","minLength":1,"maxLength":200},"stockOnHand":{"type":"string","minLength":1,"maxLength":200},"reference":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"name":{"description":"Name shown in the import history of the Epinium app. Defaults to the uploaded file name.","type":"string","maxLength":200}},"required":["connection"],"additionalProperties":false}}}},"responses":{"202":{"description":"202","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["cost_import"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"kind":{"type":"string","enum":["costs","purchases"]},"name":{"type":"string"},"status":{"type":"string","enum":["pending","processing","finished","finished_with_errors","error"],"description":"`processing` while the rows are applied; `finished` when every row was applied or skipped; `finished_with_errors` when some rows were rejected (see `rejected_rows`); `error` when the import could not run at all (see `error`)."},"total_rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows sent to the import (empty rows and `not_sent` excluded)."},"counters":{"type":"object","properties":{"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows without any amount, or whose amounts are already the cost in place on their date. Nothing is written and they are not charged."},"rejected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["applied","skipped","rejected"],"additionalProperties":false},"error":{"nullable":true,"type":"string"},"created_at":{"type":"string"},"finished_at":{"nullable":true,"type":"string"},"not_sent":{"type":"array","items":{"type":"object","properties":{"file_index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Position of the row's file in the `file_ids` that created the import, from 0; `0` when the rows came in the request."},"row":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Row of the file as the user sees it (the header is row 1)."},"sku":{"type":"string"},"reason":{"type":"string","enum":["cell_too_long"]},"column":{"type":"string"}},"required":["file_index","row","sku","reason","column"],"additionalProperties":false},"description":"Rows left out before importing because a cell is longer than the template allows. They are not in `total_rows` nor in `counters`: fix them and import them again. Up to 50, in file order; `not_sent_total` has how many there are."},"not_sent_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many rows were left out, `not_sent` included."}},"required":["object","id","connection","kind","name","status","total_rows","counters","error","created_at","finished_at","not_sent","not_sent_total"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"502":{"description":"502","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/cost-imports/{id}":{"get":{"summary":"Status of a cost import and its rejected rows","tags":["cost-imports"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"page","in":"query","description":"Page of `rejected_rows`, starting at 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"limit","in":"query","description":"Rejected rows per page (max 500).","schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["cost_import"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"kind":{"type":"string","enum":["costs","purchases"]},"name":{"type":"string"},"status":{"type":"string","enum":["pending","processing","finished","finished_with_errors","error"],"description":"`processing` while the rows are applied; `finished` when every row was applied or skipped; `finished_with_errors` when some rows were rejected (see `rejected_rows`); `error` when the import could not run at all (see `error`)."},"total_rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows sent to the import (empty rows and `not_sent` excluded)."},"counters":{"type":"object","properties":{"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows without any amount, or whose amounts are already the cost in place on their date. Nothing is written and they are not charged."},"rejected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["applied","skipped","rejected"],"additionalProperties":false},"error":{"nullable":true,"type":"string"},"created_at":{"type":"string"},"finished_at":{"nullable":true,"type":"string"},"rejected_rows":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"file_index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Position of the row's file in the `file_ids` that created the import, from 0; `0` when the rows came in the request."},"row":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Row of the file as the user sees it (the header is row 1)."},"sku":{"type":"string"},"marketplace":{"nullable":true,"type":"string"},"reason":{"type":"string","enum":["missing_sku","invalid_amount","invalid_currency","invalid_date","future_date","currency_required","ambiguous_amount","sku_not_found","outside_whitelist","marketplace_not_found","missing_exchange_rate","missing_marketplace_currency","invalid_unit_cost","future_cost","stock_group_out_of_scope","invalid_units","invalid_stock_on_hand","stock_on_hand_unknown","marketplace_required","not_client_stock","cost_from_purchases","duplicate_reference","prior_stock_value_required","parent_product"]}},"required":["file_index","row","sku","marketplace","reason"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["data","total","page","limit"],"additionalProperties":false,"description":"Rows that were not applied, with why. `sku_not_found` means the SKU is not in that connection (or not in `marketplace`); `outside_whitelist` means the product is outside the whitelist of the account (or the products visible during the trial), so it cannot be changed; `currency_required` means the row has no marketplace and no currency; `ambiguous_amount` is an amount like `1.234` that could be thousands or decimals."}},"required":["object","id","connection","kind","name","status","total_rows","counters","error","created_at","finished_at","rejected_rows"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns":{"get":{"summary":"List the authenticated account's advertising campaigns","tags":["campaigns"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the campaign name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Created `PAUSED` unless you pass `state: \"ENABLED\"` explicitly: an enabled campaign starts spending as soon as Amazon accepts it. `dailyBudget` is checked against the marketplace minimum for the connection country and rejected with 400 below it. Requires the `campaigns:write` scope and an `Idempotency-Key` header. Sponsored Brands and Sponsored Display campaigns cannot be created here yet; they can be changed and archived like any other.","summary":"Create a Sponsored Products campaign, paused by default","tags":["campaigns"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string","minLength":1,"maxLength":128},"dailyBudget":{"type":"number","minimum":0,"exclusiveMinimum":true},"targetingType":{"type":"string","enum":["AUTO","MANUAL"]},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["connection","name","dailyBudget","targetingType"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/budget-usage":{"get":{"description":"One row per ENABLED campaign with a reading from Amazon's budget usage API, which Epinium polls every 30 minutes for every Sponsored Products, Brands and Display campaign, ordered from the highest usage down. This is today's spend as Amazon counts it against the daily budget, not report data: reports, and every metrics route, only reach yesterday. `usage` is a fraction (0.85 = 85%) and can exceed 1. A campaign without a reading in the last 24 hours is not listed: the account is not covered yet, or the campaign was enabled after the last poll. A page can hold fewer rows than `limit` when a reading does not match an enabled campaign of this account (paused since that reading, for instance); `has_more` is what says whether there are more. Monetary amounts are decimal strings.","summary":"How much of its daily budget each campaign has spent today","tags":["campaigns"],"parameters":[{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"Epinium id of one campaign, to read only that one.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"min_usage","in":"query","description":"Only campaigns that have spent at least this share of their daily budget today, as a fraction: 0.8 = 80%.","schema":{"type":"number","minimum":0}},{"name":"limit","in":"query","description":"Page size, up to 500. Paginate with `offset`: rows are ordered by usage, not by id. Use `min_usage` to get only the campaigns that matter instead of walking every page.","schema":{"default":100,"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign_id":{"type":"string","description":"Amazon id of the campaign."},"name":{"type":"string"},"ad_product":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"budget":{"type":"string","description":"Daily budget Amazon measured the usage against, in the campaign currency."},"currency":{"nullable":true,"type":"string"},"usage":{"type":"number","description":"Share of the daily budget already spent today (0.85 = 85%). It can go above 1: Amazon lets a campaign spend past its daily budget."},"spent":{"type":"string","description":"`budget` times `usage`: what the campaign has spent today according to that reading. Not a report figure."},"usage_updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"When Amazon last evaluated the usage, in UTC. Amazon resets the usage to zero when the day starts, so a campaign that has not spent yet today shows the start of the day here."}},"required":["id","campaign_id","name","ad_product","connection","country","budget","currency","usage","spent","usage_updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/{id}":{"get":{"tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Send only the fields you want to change; anything you omit is left as it is. At least one field is required. A campaign that does not exist, or belongs to another account, is a 404 - never a 403, which would confirm it exists. A campaign managed by the optimizer is refused, because its next run would overwrite you. If Amazon rejects the change the response is still 200 with `result: \"failed\"` and the reason, so you can tell \"Amazon said no\" from \"the call never happened\". Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Change the state, budget, name or portfolio of a campaign","tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"dailyBudget":{"type":"number","minimum":0,"exclusiveMinimum":true},"name":{"type":"string","minLength":1,"maxLength":128},"portfolioId":{"description":"Amazon id of the portfolio to move the campaign into (the `portfolioId` of the portfolios resource), or null to take it out of its portfolio. It must belong to the same advertising account as the campaign.","nullable":true,"type":"string","minLength":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Archiving is how Amazon removes an entity, and it CANNOT BE UNDONE: an archived campaign does not come back, and this is the only irreversible operation in this API. That is why it is its own verb instead of a `state` you could set by accident while changing a bid. Use `state: \"PAUSED\"` if you only want to stop it - that one is reversible. A campaign that does not exist, or belongs to another account, is a 404. One managed by the optimizer is refused. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Archive a campaign","tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/{id}/optimization-history":{"get":{"description":"Only changes that were APPLIED, and only for real: a dry-run simulation never appears here, under any parameter. Aggregated to a net per entity — `data` carries one row per target whose bid was moved, with the bid from before the first change against the bid after the last one, so a target raised then capped back down reports `direction: unchanged` with `change_count: 2`. That is the reading a flat decision list hides, and it is usually the answer to whether the optimization is doing anything. Proposals are excluded: the optimizer computes a bid the economic ceiling can then cut, and only what reached Amazon is reported. Non-bid changes (harvested keywords, negatives, placement adjustments, blocked or quarantined targets) do not share the table because they have no previous bid — they are counted in `other_changes`. Monetary amounts are decimal strings. The window is capped at 90 days, which is the retention of the underlying records.","summary":"Changes the workflow actually applied to this campaign","tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"start_date","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"limit","in":"query","description":"Page size, up to 500. Paginate with `offset`, not with a cursor: these rows are aggregated changes, not records with an id. Narrow the window with `start_date` / `end_date` instead of walking every page.","schema":{"default":100,"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"entity_type":{"type":"string","enum":["target"]},"adgroup":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"first_bid":{"nullable":true,"type":"string"},"last_bid":{"type":"string"},"net_change":{"nullable":true,"type":"string"},"direction":{"nullable":true,"type":"string","enum":["raised","lowered","unchanged"]},"change_count":{"type":"number"},"first_change_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"last_change_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"last_reason":{"nullable":true,"type":"string"},"last_scenario":{"nullable":true,"type":"string"}},"required":["id","entity_type","adgroup","first_bid","last_bid","net_change","direction","change_count","first_change_at","last_change_at","last_reason","last_scenario"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"other_changes":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string","enum":["target","searchTerm","campaign"]},"entity_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"change_type":{"type":"string"},"count":{"type":"number"},"last_change_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"last_reason":{"nullable":true,"type":"string"}},"required":["entity_type","entity_id","change_type","count","last_change_at","last_reason"],"additionalProperties":false}},"summary":{"type":"object","properties":{"targets_touched":{"type":"number"},"bid_changes":{"type":"number"},"raised":{"type":"number"},"lowered":{"type":"number"},"unchanged":{"type":"number"},"other_changes":{"type":"number"},"window":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"}},"required":["start_date","end_date"],"additionalProperties":false}},"required":["targets_touched","bid_changes","raised","lowered","unchanged","other_changes","window"],"additionalProperties":false}},"required":["object","data","has_more","other_changes","summary"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/full":{"post":{"description":"One call for the whole structure, in order: campaign, ad group, targets, product ads. There is NO rollback on Amazon — if a later step fails the earlier entities stay created, and the response tells you how far it got in `stopped_at` plus what went wrong in `partial_errors`. Read that instead of retrying: a retry would create a second campaign. Everything is created paused unless you ask otherwise. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Create a campaign with its ad group, targets and product ads","tags":["campaigns"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string","minLength":1,"maxLength":128},"dailyBudget":{"type":"number","minimum":0,"exclusiveMinimum":true},"targetingType":{"type":"string","enum":["AUTO","MANUAL"]},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["connection","name","dailyBudget","targetingType"],"additionalProperties":false},"adGroup":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":255},"defaultBid":{"type":"number","minimum":0,"exclusiveMinimum":true},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]}},"required":["name","defaultBid"],"additionalProperties":false},"targets":{"maxItems":1000,"type":"array","items":{"type":"object","properties":{"targetType":{"type":"string","enum":["KEYWORD","PRODUCT","PRODUCT_CATEGORY","THEME","PRODUCT_AUDIENCE","AUDIENCE","CONTENT_CATEGORY","LOCATION"],"description":"Sponsored Products: KEYWORD, PRODUCT, PRODUCT_CATEGORY. Sponsored Brands: those plus THEME. Sponsored Display: all of them. The ad product is the one of the ad group."},"negative":{"default":false,"type":"boolean"},"keywordText":{"type":"string"},"matchType":{"type":"string","enum":["EXACT","PHRASE","BROAD"]},"asin":{"type":"string"},"sku":{"description":"Sponsored Display PRODUCT only: target a product by SKU instead of ASIN.","type":"string"},"productMatchType":{"description":"PRODUCT and PRODUCT_AUDIENCE. Sponsored Products: ASIN_SAME_AS or ASIN_EXPANDED_FROM. Sponsored Brands: PRODUCT_EXACT. Sponsored Display: PRODUCT_EXACT or PRODUCT_SIMILAR.","type":"string"},"category":{"type":"string"},"productBrand":{"description":"PRODUCT_CATEGORY refinement: brand id.","type":"string"},"productPriceGreaterThan":{"type":"number"},"productPriceLessThan":{"type":"number"},"productRatingGreaterThan":{"type":"number"},"productRatingLessThan":{"type":"number"},"productAgeRange":{"description":"Sponsored Display PRODUCT_CATEGORY refinement: age range id.","type":"string"},"productPrimeShippingEligible":{"description":"Sponsored Display PRODUCT_CATEGORY refinement.","type":"boolean"},"themeMatchType":{"description":"THEME. Sponsored Brands: KEYWORDS_RELATED_TO_YOUR_BRAND or KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES. Sponsored Display: INTERESTED_AUDIENCE.","type":"string","enum":["KEYWORDS_RELATED_TO_YOUR_BRAND","KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES","INTERESTED_AUDIENCE"]},"event":{"description":"Sponsored Display PRODUCT_AUDIENCE: shoppers who bought or viewed the ASIN.","type":"string","enum":["PURCHASE","VIEW"]},"lookback":{"description":"Sponsored Display PRODUCT_AUDIENCE, in days: 7, 14, 30, 60, 90, 180 or 365.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"audienceId":{"description":"Sponsored Display AUDIENCE: Amazon audience id.","type":"string"},"contentCategoryId":{"description":"Sponsored Display CONTENT_CATEGORY: Amazon content category id.","type":"string"},"locationId":{"description":"Sponsored Display LOCATION: Amazon location id.","type":"string"},"bid":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["targetType"],"additionalProperties":false}},"productAds":{"maxItems":1000,"type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]}},"required":["product"],"additionalProperties":false}}},"required":["campaign","adGroup"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adgroup":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"targets_created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"product_ads_created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stopped_at":{"type":"string","enum":["campaign","adgroup","targets","productAds","done"]},"partial_errors":{"type":"array","items":{"type":"string"}}},"required":["success","campaign","adgroup","targets_created","product_ads_created","stopped_at","partial_errors"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/{id}/optimization-config":{"patch":{"description":"Sets what the optimizer chases for this campaign: target ACOS or ROAS, bid floor and ceiling, monthly budget, harvesting overrides, and which workflows may touch it. None of this reaches Amazon - it is the configuration Epinium optimizes against, so no `Idempotency-Key` is required. Read the current values with `GET /v1/campaigns/:id?expand[]=optimizationConfig`. **What puts a campaign under the optimizer is `linkedWorkflowDefinitionIds`: a workflow listed there processes it every night and moves real bids on Amazon** - confirm it with the person first, exactly as you would turning a workflow on. A workflow that selects campaigns on its own can also pick it up, and `workflowsOptOut: true` is what declines that; the only setting that always keeps a workflow away is `excludedWorkflowDefinitionIds`, which wins over the other two. `aiEnabled` is NOT that switch: it records the account holder consent, travels to Amazon as the `epinium:ai_enabled` tag, so `aiEnabled: false` does NOT take a campaign out of the optimizer - remove it from `linkedWorkflowDefinitionIds` (plus `workflowsOptOut: true` if the workflow selects campaigns on its own) or add the workflow to `excludedWorkflowDefinitionIds` instead. `optimizeDate` and `optimizingSince` are read-only, stamped by the optimizer itself, and sending either is a 400. Requires `campaigns:write`.","summary":"Update Epinium's own optimization settings for a campaign","tags":["campaigns"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"aiEnabled":{"description":"The account holder's consent flag. It is exported to Amazon as the `epinium:ai_enabled` tag. It does NOT put the campaign under the optimizer and does NOT take it out: that is `linkedWorkflowDefinitionIds` and `excludedWorkflowDefinitionIds`.","type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"nullable":true,"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}}},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}}},"budget":{"description":"The optimizer's own spend targets. `dailyBudget` here is NOT the campaign's Amazon daily budget: it is the pacing anchor the optimizer spends against, and nothing in this block travels to Amazon. The real Amazon budget is the `budget` field of the campaign resource, changed with `PATCH /v1/campaigns/:id`. Two different things with the same name.","nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}}},"harvesting":{"description":"Per-campaign harvesting overrides, merged field by field. There is no cross-campaign harvesting: the optimizer never moves a search term into a different campaign.","nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string","enum":["bids-only","harvesting","discovery"]},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"additionalProperties":false},"warmingModeUntil":{"description":"ISO-8601 timestamp until which the campaign stays in warming mode, or `null` to clear it. A UTC `Z` timestamp or one with a numeric offset both work; anything that is not a valid ISO-8601 datetime is rejected with a 400.","nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"linkedWorkflowDefinitionIds":{"description":"Force-include: every workflow listed here processes this campaign each night, skipping its own selection filter. **This is what puts a campaign under the optimizer, which moves real bids on Amazon** - confirm it with the person before adding one. Replaces the whole list.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"description":"Force-exclude, and it wins over the other two: a workflow listed here never touches this campaign, whatever else is set. This is how you reliably take a campaign out of the optimizer. Replaces the whole list.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"description":"Declines automatic selection: with `true`, only the workflows in `linkedWorkflowDefinitionIds` process this campaign. It only bites on workflows that select campaigns by themselves - against a workflow that has this campaign linked it changes nothing.","type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"paths":{"type":"array","items":{"type":"string"}},"reason":{"nullable":true,"type":"string","enum":["not_found","unowned_workflow","validation"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","paths","reason","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/optimization-config/batch":{"post":{"description":"NOT all-or-nothing: `data` carries one row per campaign you sent, in the order you sent them. A row that fails validation comes back `failed` with the reason and the others still apply, because each campaign is validated against its OWN stored state - a bid ceiling that is mandatory for one objective may be absent in another campaign. **The warning about `linkedWorkflowDefinitionIds` applies to every row**: enrolling a batch puts all of those campaigns under a workflow that moves real bids on Amazon every night, so confirm it with the person before doing it wholesale. `aiEnabled` is consent and an Amazon tag, not the enrolment switch, in the batch exactly as in the single. Requires `campaigns:write`.","summary":"Same update for up to 1000 campaigns, one patch per row","tags":["campaigns"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"aiEnabled":{"description":"The account holder's consent flag. It is exported to Amazon as the `epinium:ai_enabled` tag. It does NOT put the campaign under the optimizer and does NOT take it out: that is `linkedWorkflowDefinitionIds` and `excludedWorkflowDefinitionIds`.","type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"nullable":true,"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}}},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}}},"budget":{"description":"The optimizer's own spend targets. `dailyBudget` here is NOT the campaign's Amazon daily budget: it is the pacing anchor the optimizer spends against, and nothing in this block travels to Amazon. The real Amazon budget is the `budget` field of the campaign resource, changed with `PATCH /v1/campaigns/:id`. Two different things with the same name.","nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}}},"harvesting":{"description":"Per-campaign harvesting overrides, merged field by field. There is no cross-campaign harvesting: the optimizer never moves a search term into a different campaign.","nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string","enum":["bids-only","harvesting","discovery"]},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"additionalProperties":false},"warmingModeUntil":{"description":"ISO-8601 timestamp until which the campaign stays in warming mode, or `null` to clear it. A UTC `Z` timestamp or one with a numeric offset both work; anything that is not a valid ISO-8601 datetime is rejected with a 400.","nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"linkedWorkflowDefinitionIds":{"description":"Force-include: every workflow listed here processes this campaign each night, skipping its own selection filter. **This is what puts a campaign under the optimizer, which moves real bids on Amazon** - confirm it with the person before adding one. Replaces the whole list.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"description":"Force-exclude, and it wins over the other two: a workflow listed here never touches this campaign, whatever else is set. This is how you reliably take a campaign out of the optimizer. Replaces the whole list.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"description":"Declines automatic selection: with `true`, only the workflows in `linkedWorkflowDefinitionIds` process this campaign. It only bites on workflows that select campaigns by themselves - against a workflow that has this campaign linked it changes nothing.","type":"boolean"},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"paths":{"type":"array","items":{"type":"string"}},"reason":{"nullable":true,"type":"string","enum":["not_found","unowned_workflow","validation"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","paths","reason","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaigns/batch":{"post":{"description":"Same fields as the single update, up to 1000 campaigns per call - the cap is the per-request limit Amazon itself declares. NOT all-or-nothing: `data` carries one row per campaign you sent, in the order you sent them, and `applied` is what actually reached Amazon. Only `applied` rows are billed. A campaign is `applied` only when EVERY field you asked for went through: if the state changes and the budget is rejected, that campaign is `failed` with the reason, because reporting it as applied is how an agent concludes the budget moved when it did not. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Change state, budget, name or portfolio on up to 1000 campaigns","tags":["campaigns"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"dailyBudget":{"type":"number","minimum":0,"exclusiveMinimum":true},"name":{"type":"string","minLength":1,"maxLength":128},"portfolioId":{"description":"Amazon id of the portfolio to move the campaign into (the `portfolioId` of the portfolios resource), or null to take it out of its portfolio. It must belong to the same advertising account as the campaign.","nullable":true,"type":"string","minLength":1},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/portfolios":{"get":{"summary":"List the authenticated account's portfolios and their budget caps","tags":["portfolios"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"search","in":"query","description":"Case-insensitive substring match over the portfolio name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"portfolioId":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"budget":{"nullable":true,"type":"object","properties":{"policy":{"nullable":true,"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE","NO_CAP","OTHER"]},"amount":{"nullable":true,"type":"number"},"currencyCode":{"nullable":true,"type":"string"},"startDate":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["policy","amount","currencyCode","startDate","endDate"],"additionalProperties":false},"inBudget":{"nullable":true,"type":"boolean"},"servingStatus":{"nullable":true,"type":"string"},"statusReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","portfolioId","name","state","connection","country","budget","inBudget","servingStatus","statusReasons","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Creates a portfolio in the Amazon Ads account of `connection`. `budget` caps what ALL the campaigns in the portfolio can spend together: `MONTHLY_RECURRING` resets every month, `DATE_RANGE` applies between `startDate` and `endDate`, `NO_CAP` removes the cap. The currency is the marketplace one; you do not send it. If Amazon rejects the portfolio the response is still 201 with `result: \"failed\"`, the reason in `error` and `id: null`. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Create a portfolio, optionally with a budget cap","tags":["portfolios"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string","minLength":1,"maxLength":255},"state":{"default":"ENABLED","type":"string","enum":["ENABLED","PAUSED"]},"budget":{"type":"object","properties":{"policy":{"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE","NO_CAP"]},"amount":{"description":"Cap amount in the marketplace currency. Required for MONTHLY_RECURRING and DATE_RANGE; omit it for NO_CAP.","type":"number","minimum":0,"exclusiveMinimum":true},"startDate":{"description":"YYYY-MM-DD. Required for DATE_RANGE.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"description":"YYYY-MM-DD. Required for DATE_RANGE.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["policy"],"additionalProperties":false}},"required":["connection","name"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/portfolios/budget-usage":{"get":{"description":"One row per ENABLED portfolio with a budget cap (`MONTHLY_RECURRING` or `DATE_RANGE`). The period is the current calendar month for `MONTHLY_RECURRING` and the portfolio's own date range for `DATE_RANGE`. Spend is the sum of ALL its campaigns (Sponsored Products, Brands and Display) up to `data_through`, which is yesterday: today is still incomplete. `status` compares the spend with the ideal linear pace for the days counted, with a ±10% band: `over_pace` will exceed the cap at this rate, `under_pace` will not use it, `cap_reached` has spent it all. `daily_to_finish` is what it can spend per day to land exactly on the cap. Monetary amounts are decimal strings; `consumed` and `elapsed` are fractions (0.6333 = 63.33%).","summary":"How much of each portfolio budget cap is spent this period","tags":["portfolios"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"portfolio_id":{"type":"string"},"name":{"type":"string"},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"policy":{"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE"]},"cap":{"type":"string","description":"Decimal string in the portfolio currency."},"currency":{"nullable":true,"type":"string"},"period_start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"period_end":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"data_through":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day whose spend is counted: yesterday, because today is still incomplete, or the end of the period if it is over."},"campaign_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spent":{"type":"string","description":"Decimal string in the portfolio currency."},"consumed":{"type":"number","description":"Share of the cap already spent (0.6333 = 63.33%)."},"elapsed":{"nullable":true,"description":"Share of the period already counted. `null` for a DATE_RANGE without end date.","type":"number"},"days_elapsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"days_remaining":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"daily_rate":{"nullable":true,"type":"string","description":"Decimal string in the portfolio currency."},"projected_spend":{"nullable":true,"description":"Spend at the end of the period at the current daily rate. `null` when there is no closed day yet or no end date.","type":"string"},"projected_vs_cap":{"nullable":true,"description":"Projected spend minus the cap: positive means it will go over.","type":"string"},"daily_to_finish":{"nullable":true,"description":"What the portfolio can spend per day from today to land exactly on the cap. `0` when the cap is already spent.","type":"string"},"status":{"type":"string","enum":["on_track","over_pace","under_pace","cap_reached","no_data_yet","not_started","ended","open_ended"]}},"required":["id","portfolio_id","name","connection","country","policy","cap","currency","period_start","period_end","data_through","campaign_count","spent","consumed","elapsed","days_elapsed","days_remaining","daily_rate","projected_spend","projected_vs_cap","daily_to_finish","status"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/portfolios/{id}":{"get":{"tags":["portfolios"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"portfolioId":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"budget":{"nullable":true,"type":"object","properties":{"policy":{"nullable":true,"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE","NO_CAP","OTHER"]},"amount":{"nullable":true,"type":"number"},"currencyCode":{"nullable":true,"type":"string"},"startDate":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["policy","amount","currencyCode","startDate","endDate"],"additionalProperties":false},"inBudget":{"nullable":true,"type":"boolean"},"servingStatus":{"nullable":true,"type":"string"},"statusReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","portfolioId","name","state","connection","country","budget","inBudget","servingStatus","statusReasons","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Send only what you want to change; at least one field is required. `budget` is replaced whole: send the full cap you want, not just the amount. A portfolio that does not exist, or belongs to another account, is a 404. If Amazon rejects the change the response is still 200 with `result: \"failed\"` and the reason, and nothing is changed on our side. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Change the name, state or budget cap of a portfolio","tags":["portfolios"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"state":{"type":"string","enum":["ENABLED","PAUSED"]},"budget":{"type":"object","properties":{"policy":{"type":"string","enum":["MONTHLY_RECURRING","DATE_RANGE","NO_CAP"]},"amount":{"description":"Cap amount in the marketplace currency. Required for MONTHLY_RECURRING and DATE_RANGE; omit it for NO_CAP.","type":"number","minimum":0,"exclusiveMinimum":true},"startDate":{"description":"YYYY-MM-DD. Required for DATE_RANGE.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"description":"YYYY-MM-DD. Required for DATE_RANGE.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["policy"],"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/campaign-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window. Unlike the rest of the API, this resource paginates with `limit`/`offset` (an aggregated row has no id to use as a cursor) and `has_more` tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per campaign, from the account's report history","tags":["campaign-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`). Every metrics call costs a charge per day of the window (1 to 8 credits per day depending on the resource) plus 1 credit per row returned, so a grouped call costs about the window charge alone, and a shorter window is usually what lowers the price most. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country"]}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SB","SD"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["campaign_metrics"]},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_product":{"type":"string","enum":["SP","SB","SD"]},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string","description":"Total attributed sales: click plus view. Sponsored Products has no view attribution, so there it equals sales_clicks. acos and roas are computed on this total. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_clicks":{"type":"string","description":"Sales attributed to ad clicks only. For Sponsored Brands and Sponsored Display, sales minus this is what view attribution added. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_views":{"type":"string","description":"Sales attributed to ad views: sales minus sales_clicks. Always 0 on Sponsored Products."},"orders":{"type":"number","description":"Total attributed orders: click plus view on Sponsored Brands and Sponsored Display; on Sponsored Products it equals click orders. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"units":{"type":"number","description":"Units sold attributed to ad clicks only; view-attributed units are not included. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"description":"Click-attributed orders divided by clicks. View-attributed orders are left out, since they could push the rate above 1; orders itself is the total.","type":"number"},"top_of_search_is":{"nullable":true,"type":"number"},"new_to_brand_sales":{"nullable":true,"type":"string"},"new_to_brand_purchases":{"nullable":true,"type":"number"},"detail_page_views":{"nullable":true,"type":"number"},"viewable_impressions":{"nullable":true,"type":"number"}},"required":["object","campaign","connection","country","ad_product","currency","impressions","clicks","cost","sales","sales_clicks","sales_views","orders","units","ctr","cpc","acos","roas","conversion_rate","top_of_search_is","new_to_brand_sales","new_to_brand_purchases","detail_page_views","viewable_impressions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/adgroups":{"get":{"summary":"List the authenticated account's ad groups","tags":["adgroups"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the ad group name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Created `PAUSED` unless you pass `state: \"ENABLED\"`. `defaultBid` is clamped to the marketplace bid limits for the campaign country, so a bid outside them is adjusted rather than rejected. The campaign must already be published on Amazon; one that belongs to another account is a 404, never a 403. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Create an ad group inside a Sponsored Products campaign","tags":["adgroups"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string","minLength":3,"maxLength":255},"defaultBid":{"type":"number","minimum":0,"exclusiveMinimum":true},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]},"targetType":{"type":"string","enum":["auto","keyword","product"]}},"required":["campaign","name","defaultBid"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/adgroups/{id}":{"get":{"tags":["adgroups"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Send only the fields you want to change; anything you omit is left as it is. At least one field is required. `defaultBid` is checked against the marketplace bid limits before it is sent, so an out-of-range bid comes back with the limits instead of a generic rejection from Amazon. An ad group that does not exist, or belongs to another account, is a 404 - never a 403, which would confirm it exists. One managed by the optimizer is refused, because its next run would overwrite you. If Amazon rejects the change the response is still 200 with `result: \"failed\"` and the reason. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Change the state, default bid or name of an ad group","tags":["adgroups"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"defaultBid":{"type":"number","minimum":0,"exclusiveMinimum":true},"name":{"type":"string","minLength":3,"maxLength":255}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Archiving is how Amazon removes an entity, and it CANNOT BE UNDONE: an archived ad group does not come back, and this is the only irreversible operation in this API. That is why it is its own verb instead of a `state` you could set by accident while changing a bid. Use `state: \"PAUSED\"` if you only want to stop it - that one is reversible. An ad group that does not exist, or belongs to another account, is a 404. One managed by the optimizer is refused. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Archive a ad group","tags":["adgroups"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/adgroups/batch":{"post":{"description":"Same fields as the single update, up to 1000 ad groups per call - the cap is the per-request limit Amazon itself declares. NOT all-or-nothing: `data` carries one row per ad group you sent, in the order you sent them, and `applied` is what actually reached Amazon. Only `applied` rows are billed. An ad group is `applied` only when EVERY field you asked for went through. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Change state, default bid or name on up to 1000 ad groups","tags":["adgroups"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"defaultBid":{"type":"number","minimum":0,"exclusiveMinimum":true},"name":{"type":"string","minLength":3,"maxLength":255},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/adgroup-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window. Like the rest of the metrics resources it paginates with `limit`/`offset` (an aggregated row has no id to use as a cursor) and `has_more` tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per ad group, from the account's report history","tags":["adgroup-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`). Every metrics call costs a charge per day of the window (1 to 8 credits per day depending on the resource) plus 1 credit per row returned, so a grouped call costs about the window charge alone, and a shorter window is usually what lowers the price most. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country"]}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_group","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SB","SD"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["adgroup_metrics"]},"ad_group":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_product":{"type":"string","enum":["SP","SB","SD"]},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string","description":"Total attributed sales: click plus view. Sponsored Products has no view attribution, so there it equals sales_clicks. acos and roas are computed on this total. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_clicks":{"type":"string","description":"Sales attributed to ad clicks only. For Sponsored Brands and Sponsored Display, sales minus this is what view attribution added. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_views":{"type":"string","description":"Sales attributed to ad views: sales minus sales_clicks. Always 0 on Sponsored Products."},"orders":{"type":"number","description":"Total attributed orders: click plus view on Sponsored Brands and Sponsored Display; on Sponsored Products it equals click orders. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"units":{"type":"number","description":"Units sold attributed to ad clicks only; view-attributed units are not included. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"description":"Click-attributed orders divided by clicks. View-attributed orders are left out, since they could push the rate above 1; orders itself is the total.","type":"number"},"new_to_brand_sales":{"nullable":true,"type":"string"},"new_to_brand_purchases":{"nullable":true,"type":"number"},"detail_page_views":{"nullable":true,"type":"number"},"viewable_impressions":{"nullable":true,"type":"number"}},"required":["object","ad_group","campaign","ad_product","connection","country","currency","impressions","clicks","cost","sales","sales_clicks","sales_views","orders","units","ctr","cpc","acos","roas","conversion_rate","new_to_brand_sales","new_to_brand_purchases","detail_page_views","viewable_impressions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/targets":{"get":{"summary":"List the authenticated account's advertising targets","tags":["targets"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the target's expression (keyword, ASIN or category, chosen by `targetType`) and its `matchType`; with `targetType` set, only that type's field is searched. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"adGroup","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}},{"name":"targetType","in":"query","schema":{"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]}},{"name":"negative","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"targetId":{"nullable":true,"type":"string"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"negative":{"type":"boolean"},"bid":{"nullable":true,"type":"number"},"targetType":{"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]},"targetLevel":{"nullable":true,"type":"string","enum":["CAMPAIGN","AD_GROUP"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","targetId","connection","country","campaign","adGroup","state","negative","bid","targetType","targetLevel","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Creates up to 1000 targets in one call — the cap is Amazon's own per-request limit. NOT all-or-nothing: the response counts what went in and lists every rejection in `failure_details` with its reason, so a partial result is actionable instead of a retry that duplicates what already worked. Amazon rules are enforced before sending (negative keyword length and word count, category id coercion) and the ad group capacity is checked against the Amazon limits. The response returns COUNTS, not ids: list the ad group targets to get them. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Create keyword, product or category targets in an ad group","tags":["targets"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"adgroup":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"targets":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"targetType":{"type":"string","enum":["KEYWORD","PRODUCT","PRODUCT_CATEGORY","THEME","PRODUCT_AUDIENCE","AUDIENCE","CONTENT_CATEGORY","LOCATION"],"description":"Sponsored Products: KEYWORD, PRODUCT, PRODUCT_CATEGORY. Sponsored Brands: those plus THEME. Sponsored Display: all of them. The ad product is the one of the ad group."},"negative":{"default":false,"type":"boolean"},"keywordText":{"type":"string"},"matchType":{"type":"string","enum":["EXACT","PHRASE","BROAD"]},"asin":{"type":"string"},"sku":{"description":"Sponsored Display PRODUCT only: target a product by SKU instead of ASIN.","type":"string"},"productMatchType":{"description":"PRODUCT and PRODUCT_AUDIENCE. Sponsored Products: ASIN_SAME_AS or ASIN_EXPANDED_FROM. Sponsored Brands: PRODUCT_EXACT. Sponsored Display: PRODUCT_EXACT or PRODUCT_SIMILAR.","type":"string"},"category":{"type":"string"},"productBrand":{"description":"PRODUCT_CATEGORY refinement: brand id.","type":"string"},"productPriceGreaterThan":{"type":"number"},"productPriceLessThan":{"type":"number"},"productRatingGreaterThan":{"type":"number"},"productRatingLessThan":{"type":"number"},"productAgeRange":{"description":"Sponsored Display PRODUCT_CATEGORY refinement: age range id.","type":"string"},"productPrimeShippingEligible":{"description":"Sponsored Display PRODUCT_CATEGORY refinement.","type":"boolean"},"themeMatchType":{"description":"THEME. Sponsored Brands: KEYWORDS_RELATED_TO_YOUR_BRAND or KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES. Sponsored Display: INTERESTED_AUDIENCE.","type":"string","enum":["KEYWORDS_RELATED_TO_YOUR_BRAND","KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES","INTERESTED_AUDIENCE"]},"event":{"description":"Sponsored Display PRODUCT_AUDIENCE: shoppers who bought or viewed the ASIN.","type":"string","enum":["PURCHASE","VIEW"]},"lookback":{"description":"Sponsored Display PRODUCT_AUDIENCE, in days: 7, 14, 30, 60, 90, 180 or 365.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"audienceId":{"description":"Sponsored Display AUDIENCE: Amazon audience id.","type":"string"},"contentCategoryId":{"description":"Sponsored Display CONTENT_CATEGORY: Amazon content category id.","type":"string"},"locationId":{"description":"Sponsored Display LOCATION: Amazon location id.","type":"string"},"bid":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["targetType"],"additionalProperties":false}}},"required":["adgroup","targets"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failure_details":{"type":"array","items":{"type":"object","properties":{"reference":{"nullable":true,"type":"string"},"error":{"type":"string"}},"required":["reference","error"],"additionalProperties":false}}},"required":["created","failed","failure_details"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/targets/{id}":{"get":{"tags":["targets"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"targetId":{"nullable":true,"type":"string"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"negative":{"type":"boolean"},"bid":{"nullable":true,"type":"number"},"targetType":{"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]},"targetLevel":{"nullable":true,"type":"string","enum":["CAMPAIGN","AD_GROUP"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","targetId","connection","country","campaign","adGroup","state","negative","bid","targetType","targetLevel","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Send only the fields you want to change; anything you omit is left as it is. At least one field is required. Only state and bid: what defines a target - its keyword, its ASIN, its match type - is not editable on Amazon, so to change that you create another and archive this one. A negative target has no bid and asking for one is refused. `bid` is checked against the marketplace limits before it is sent. A target that does not exist, or belongs to another account, is a 404 - never a 403. If Amazon rejects the change the response is still 200 with `result: \"failed\"`. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Change the state or bid of a target","tags":["targets"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"bid":{"type":"number","minimum":0,"exclusiveMinimum":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Archiving is how Amazon removes an entity, and it CANNOT BE UNDONE: an archived target does not come back, and this is the only irreversible operation in this API. That is why it is its own verb instead of a `state` you could set by accident while changing a bid. Use `state: \"PAUSED\"` if you only want to stop it - that one is reversible. A target that does not exist, or belongs to another account, is a 404. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Archive a target","tags":["targets"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/targets/batch":{"post":{"description":"This is the bid sweep: up to 1000 targets in ONE call, each with its own bid - the cap is the per-request limit Amazon itself declares. Prefer it over calling the single update in a loop. NOT all-or-nothing: `data` carries one row per target you sent, in the order you sent them, and `applied` is what actually reached Amazon. Only `applied` rows are billed, so a partial result costs you only what worked. A target is `applied` only when EVERY field you asked for went through. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Change state or bid on up to 1000 targets","tags":["targets"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"bid":{"type":"number","minimum":0,"exclusiveMinimum":true},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/target-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window, with the target type and keyword resolved from the catalog. This is one of the two heaviest resources, so its window is capped shorter: 93 days for `granularity=total` and 31 for `daily`. Paginates with `limit`/`offset` and `has_more` tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per target, from the account's report history","tags":["target-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`). Every metrics call costs a charge per day of the window (1 to 8 credits per day depending on the resource) plus 1 credit per row returned, so a grouped call costs about the window charge alone, and a shorter window is usually what lowers the price most. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country"]}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_group","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"target","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SB","SD"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["target_metrics"]},"target":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"target_type":{"nullable":true,"type":"string"},"match_type":{"nullable":true,"type":"string"},"target_expression":{"nullable":true,"type":"string"},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_group":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_product":{"type":"string","enum":["SP","SB","SD"]},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string","description":"Total attributed sales: click plus view. Sponsored Products has no view attribution, so there it equals sales_clicks. acos and roas are computed on this total. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_clicks":{"type":"string","description":"Sales attributed to ad clicks only. For Sponsored Brands and Sponsored Display, sales minus this is what view attribution added. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_views":{"type":"string","description":"Sales attributed to ad views: sales minus sales_clicks. Always 0 on Sponsored Products."},"orders":{"type":"number","description":"Total attributed orders: click plus view on Sponsored Brands and Sponsored Display; on Sponsored Products it equals click orders. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"units":{"type":"number","description":"Units sold attributed to ad clicks only; view-attributed units are not included. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"description":"Click-attributed orders divided by clicks. View-attributed orders are left out, since they could push the rate above 1; orders itself is the total.","type":"number"},"new_to_brand_sales":{"nullable":true,"type":"string"},"new_to_brand_purchases":{"nullable":true,"type":"number"},"detail_page_views":{"nullable":true,"type":"number"},"viewable_impressions":{"nullable":true,"type":"number"}},"required":["object","target","target_type","match_type","target_expression","campaign","ad_group","ad_product","connection","country","currency","impressions","clicks","cost","sales","sales_clicks","sales_views","orders","units","ctr","cpc","acos","roas","conversion_rate","new_to_brand_sales","new_to_brand_purchases","detail_page_views","viewable_impressions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-ads":{"get":{"summary":"List the authenticated account's advertising product ads","tags":["product-ads"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the advertised ASIN and SKU. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"adGroup","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"product","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adId":{"nullable":true,"type":"string"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"product":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"cost":{"nullable":true,"description":"Product and shipping cost in force today, the same that feeds the P&L. `null` for advertising products and on plans without product cost (Free and Guru).","type":"object","properties":{"cogs":{"nullable":true,"description":"Unit cost of the product in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false},"shipping":{"nullable":true,"description":"Unit shipping cost in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false}},"required":["cogs","shipping"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","cost","createdAt","updatedAt"],"additionalProperties":false}]},"asin":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"adType":{"type":"string","enum":["PRODUCT_AD","IMAGE","VIDEO","PRODUCT_COLLECTION","STORE_SPOTLIGHT","BRAND_VIDEO"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adId","connection","country","campaign","adGroup","product","asin","sku","state","adType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"Each entry links one catalog product to the ad group. Products are resolved against YOUR catalog: one that is not there, or that lacks the identifier the account needs (ASIN for Vendor, SKU for Seller), is reported in `failure_details` with that reason instead of failing the whole call. Created `PAUSED` unless asked otherwise. The response returns COUNTS, not ids: list the ad group product ads to get them. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Advertise catalog products in an ad group","tags":["product-ads"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"adgroup":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"productAds":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"product":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"state":{"default":"PAUSED","type":"string","enum":["ENABLED","PAUSED"]}},"required":["product"],"additionalProperties":false}}},"required":["adgroup","productAds"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failure_details":{"type":"array","items":{"type":"object","properties":{"reference":{"nullable":true,"type":"string"},"error":{"type":"string"}},"required":["reference","error"],"additionalProperties":false}}},"required":["created","failed","failure_details"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-ads/{id}":{"get":{"tags":["product-ads"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adId":{"nullable":true,"type":"string"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"product":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"cost":{"nullable":true,"description":"Product and shipping cost in force today, the same that feeds the P&L. `null` for advertising products and on plans without product cost (Free and Guru).","type":"object","properties":{"cogs":{"nullable":true,"description":"Unit cost of the product in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false},"shipping":{"nullable":true,"description":"Unit shipping cost in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false}},"required":["cogs","shipping"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","cost","createdAt","updatedAt"],"additionalProperties":false}]},"asin":{"nullable":true,"type":"string"},"sku":{"nullable":true,"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"adType":{"type":"string","enum":["PRODUCT_AD","IMAGE","VIDEO","PRODUCT_COLLECTION","STORE_SPOTLIGHT","BRAND_VIDEO"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adId","connection","country","campaign","adGroup","product","asin","sku","state","adType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"State is the only writable field: a product ad links one catalog product to an ad group and has no bid or name of its own. A product ad that does not exist, or belongs to another account, is a 404 - never a 403. If Amazon rejects the change the response is still 200 with `result: \"failed\"` and the reason. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Enable or pause a product ad","tags":["product-ads"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Archiving is how Amazon removes an entity, and it CANNOT BE UNDONE: an archived product ad does not come back, and this is the only irreversible operation in this API. That is why it is its own verb instead of a `state` you could set by accident while changing a bid. Use `state: \"PAUSED\"` if you only want to stop it - that one is reversible. A product ad that does not exist, or belongs to another account, is a 404. Requires the `campaigns:write` scope and an `Idempotency-Key` header.","summary":"Archive a product ad","tags":["product-ads"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-ads/batch":{"post":{"description":"Up to 1000 product ads per call - the cap is the per-request limit Amazon itself declares. NOT all-or-nothing: `data` carries one row per product ad you sent, in the order you sent them, and `applied` is what actually reached Amazon. Only `applied` rows are billed. Requires `campaigns:write` and an `Idempotency-Key` header.","summary":"Enable or pause up to 1000 product ads","tags":["product-ads"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","PAUSED"]},"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"required":["id"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/product-ad-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window. Only Sponsored Products and Sponsored Display have product ads; Sponsored Brands does not, so `ad_product` accepts SP and SD only. Paginates with `limit`/`offset` and `has_more` tells whether another page follows. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per product ad, from the account's report history","tags":["product-ad-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`). Every metrics call costs a charge per day of the window (1 to 8 credits per day depending on the resource) plus 1 credit per row returned, so a grouped call costs about the window charge alone, and a shorter window is usually what lowers the price most. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter. `cluster` gives one row per product cluster (the `clusters` resource), with its id in `cluster` and its name in `cluster_name`. A product in several clusters counts in full in each of them, so the cluster rows do NOT add up to the account total, and products in no cluster are left out. It combines with `connection` and `country`, and with the `cluster` filter to choose which clusters come back.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country","cluster"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country","cluster"]}}]}},{"name":"cluster","in":"query","description":"Restrict the rows to the products of one or more product clusters (the `clusters` resource), by cluster id; repeat the param for several (`cluster[]=a&cluster[]=b`) and the result is their union, a product in two of them counting once. A cluster holds catalog products (one per connection and country), not ASINs: seller and vendor metrics keep exactly those products, so the same ASIN on another connection is left out unless its product is in the cluster too; product-ad metrics keep each product's ASIN in its country, across every advertising profile in scope. Combines with `group_by` (e.g. the monthly total of a product family) and with every other filter. An id that does not exist or belongs to another account contributes nothing, so the list comes back empty rather than failing. Rows that Amazon could not match to a catalog product are excluded by this filter: about 0.01% of seller sales, about 5% of vendor sales, and about 3% of product-ad spend (those rows carry no ASIN either).","schema":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_group","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"product_ad","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"asin","in":"query","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`.","schema":{"type":"string","pattern":"^[A-Z0-9]{10}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SD"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["product_ad_metrics"]},"product_ad":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"product":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"nullable":true,"type":"string"},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_group":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"cluster":{"nullable":true,"description":"Product cluster of the row, only with `group_by=cluster`; `null` otherwise.","type":"string","pattern":"^[a-f0-9]{24}$"},"cluster_name":{"nullable":true,"description":"Name of the product cluster, only with `group_by=cluster`; `null` otherwise.","type":"string"},"ad_product":{"type":"string","enum":["SP","SD"]},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string","description":"Total attributed sales: click plus view. Sponsored Products has no view attribution, so there it equals sales_clicks. acos and roas are computed on this total. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_clicks":{"type":"string","description":"Sales attributed to ad clicks only. For Sponsored Brands and Sponsored Display, sales minus this is what view attribution added. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_views":{"type":"string","description":"Sales attributed to ad views: sales minus sales_clicks. Always 0 on Sponsored Products."},"orders":{"type":"number","description":"Total attributed orders: click plus view on Sponsored Brands and Sponsored Display; on Sponsored Products it equals click orders. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"units":{"type":"number","description":"Units sold attributed to ad clicks only; view-attributed units are not included. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"description":"Click-attributed orders divided by clicks. View-attributed orders are left out, since they could push the rate above 1; orders itself is the total.","type":"number"},"new_to_brand_sales":{"nullable":true,"type":"string"},"new_to_brand_purchases":{"nullable":true,"type":"number"},"detail_page_views":{"nullable":true,"type":"number"},"viewable_impressions":{"nullable":true,"type":"number"}},"required":["object","product_ad","product","asin","campaign","ad_group","cluster","cluster_name","ad_product","connection","country","currency","impressions","clicks","cost","sales","sales_clicks","sales_views","orders","units","ctr","cpc","acos","roas","conversion_rate","new_to_brand_sales","new_to_brand_purchases","detail_page_views","viewable_impressions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/search-terms":{"get":{"summary":"List the authenticated account's advertising search terms","tags":["search-terms"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the shopper search term text. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"adGroup","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"searchTerm","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"searchTerm":{"type":"string"},"searchTermTargetType":{"nullable":true,"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]},"targetSourceMatchType":{"type":"string"},"lastReportDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","connection","country","campaign","adGroup","searchTerm","searchTermTargetType","targetSourceMatchType","lastReportDate","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/search-terms/{id}":{"get":{"tags":["search-terms"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"adGroup":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"adGroupId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"campaign":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adProduct":{"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"campaignId":{"nullable":true,"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ENABLED","PAUSED","ARCHIVED","OTHER"]},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"startDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"endDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"budget":{"nullable":true,"type":"object","properties":{"amount":{"type":"number"},"currency":{"nullable":true,"type":"string"},"period":{"type":"string","enum":["DAILY","LIFETIME","OTHER"]}},"required":["amount","currency","period"],"additionalProperties":false},"bidStrategy":{"nullable":true,"type":"string","enum":["MANUAL","LEGACY_FOR_SALES","AUTO_FOR_SALES","NEW_TO_BRAND","RULE_BASED"]},"portfolioId":{"nullable":true,"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizationConfig":{"nullable":true,"type":"object","properties":{"aiEnabled":{"type":"boolean"},"objective":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["ACOS","ROAS","IMPRESSIONS","ORDERS"]},"value":{"type":"number"},"maxAcosPct":{"nullable":true,"type":"number"}},"required":["type","value","maxAcosPct"],"additionalProperties":false},"limits":{"nullable":true,"type":"object","properties":{"minBid":{"nullable":true,"type":"number"},"maxBid":{"nullable":true,"type":"number"},"placementCapPercent":{"nullable":true,"type":"number"},"minSpendBeforeNegative":{"nullable":true,"type":"number"}},"required":["minBid","maxBid","placementCapPercent","minSpendBeforeNegative"],"additionalProperties":false},"budget":{"nullable":true,"type":"object","properties":{"dailyBudget":{"nullable":true,"type":"number"},"monthlyBudget":{"nullable":true,"type":"number"}},"required":["dailyBudget","monthlyBudget"],"additionalProperties":false},"harvesting":{"nullable":true,"type":"object","properties":{"discoveryLevel":{"nullable":true,"type":"string"},"competitorAsinTargeting":{"nullable":true,"type":"boolean"}},"required":["discoveryLevel","competitorAsinTargeting"],"additionalProperties":false},"linkedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"excludedWorkflowDefinitionIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"workflowsOptOut":{"type":"boolean"},"warmingModeUntil":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizeDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"optimizingSince":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["aiEnabled","objective","limits","budget","harvesting","linkedWorkflowDefinitionIds","excludedWorkflowDefinitionIds","workflowsOptOut","warmingModeUntil","optimizeDate","optimizingSince"],"additionalProperties":false}},"required":["id","adProduct","campaignId","name","state","connection","country","startDate","endDate","deliveryStatus","deliveryReasons","budget","bidStrategy","portfolioId","createdAt","updatedAt"],"additionalProperties":false}]},"defaultBid":{"nullable":true,"type":"number"},"adGroupTargetType":{"nullable":true,"type":"string","enum":["product","keyword","auto"]},"deliveryStatus":{"nullable":true,"type":"string","enum":["DELIVERING","NOT_DELIVERING","UNAVAILABLE"]},"deliveryReasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","adGroupId","name","state","connection","country","campaign","defaultBid","adGroupTargetType","deliveryStatus","deliveryReasons","createdAt","updatedAt"],"additionalProperties":false}]},"searchTerm":{"type":"string"},"searchTermTargetType":{"nullable":true,"type":"string","enum":["AUTO","KEYWORD","PRODUCT_CATEGORY","PRODUCT","PRODUCT_CATEGORY_AUDIENCE","PRODUCT_AUDIENCE","AUDIENCE","THEME","CONTENT_CATEGORY","LOCATION"]},"targetSourceMatchType":{"type":"string"},"lastReportDate":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","adProduct","connection","country","campaign","adGroup","searchTerm","searchTermTargetType","targetSourceMatchType","lastReportDate","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/skills":{"get":{"summary":"List available marketing skills","tags":["skills"],"parameters":[{"name":"search","in":"query","description":"Case-insensitive substring match over the skill name and description. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"integration","in":"query","schema":{"type":"string"}},{"name":"division","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"division":{"type":"string"},"integrations":{"type":"array","items":{"type":"string"}},"blocks":{"type":"array","items":{"type":"string","enum":["advisor","assisted","autonomous"]}},"references":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","division","integrations","blocks","references"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/skills/{id}":{"get":{"summary":"Get one skill, or one of its reference documents","tags":["skills"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"reference","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"division":{"type":"string"},"integrations":{"type":"array","items":{"type":"string"}},"blocks":{"type":"array","items":{"type":"string","enum":["advisor","assisted","autonomous"]}},"references":{"type":"array","items":{"type":"string"}},"content":{"type":"string"},"reference":{"type":"string"}},"required":["id","name","description","division","integrations","blocks","references","content"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/search-term-metrics":{"get":{"description":"Aggregated from the report history over a required `start_date`/`end_date` window, with the shopper query resolved from the catalog into `query`. Answers \"which searches do I spend most on?\": use `order_by=cost` with `limit` instead of paging. This is the heaviest resource in the API, so its window is capped shorter: 93 days for `granularity=total` and 31 for `daily`. Rows are grouped per search term AND target, because the same text can be matched by different targets. Only Sponsored Products and Sponsored Brands produce search terms, so `ad_product` accepts SP and SB only. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero. With `group_by`, rows are aggregated across entities (see the parameter) and `total_count` counts groups, or group-periods when `granularity` is not `total`.","summary":"Advertising performance per shopper search term, from the account's report history","tags":["search-term-metrics"],"parameters":[{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per entity or group. Any other value adds a `date` field with the START of each calendar period: the day, the Monday of the ISO week, or the first day of the month, quarter or year. Periods at the edges of the window are partial: `2026-01-15..2026-03-10` with `monthly` returns January (15th to 31st), February, and March (1st to 10th). `daily` has a shorter window cap than the rest.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily","weekly","monthly","quarterly","yearly"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","description":"Aggregate across entities instead of returning one row per entity. To get the account total, or a per-country or per-connection breakdown, use this INSTEAD of paging through the catalog and summing: one row per group (and per period when `granularity` is not `total`). Every metrics call costs a charge per day of the window (1 to 8 credits per day depending on the resource) plus 1 credit per row returned, so a grouped call costs about the window charge alone, and a shorter window is usually what lowers the price most. `account` collapses everything and cannot be combined with other values; `connection` and `country` can be combined by repeating the param (`group_by[]=connection&group_by[]=country`). Rows are always split by `currency` (amounts are never converted) and, in advertising, by `ad_product`. In grouped rows the entity fields (`product`, `asin`, `sku`, `campaign`, `ad_group`, `target`...) are `null`, and so are the metrics that cannot be aggregated (`rank`, `price`, `fulfillment_channel`, vendor rates and `sourcing_lead_time_days`). Seller `stock` and `days_of_coverage` are `null` too unless `country` is one of the dimensions: FBA Pan-European stock is reported in full in every marketplace, so adding it up across countries would count the same units once per country. Combines with every filter.","schema":{"anyOf":[{"type":"string","enum":["account","connection","country"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["account","connection","country"]}}]}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"country","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_group","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"target","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"search_term","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"ad_product","in":"query","schema":{"type":"string","enum":["SP","SB"]}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["cost","sales","impressions","clicks","orders","units","acos","roas","ctr","cpc","conversion_rate"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["search_term_metrics"]},"search_term":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"query":{"nullable":true,"type":"string"},"target":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_group":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"ad_product":{"type":"string","enum":["SP","SB"]},"connection":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"country":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$"},"currency":{"type":"string"},"date":{"type":"string"},"impressions":{"type":"number"},"clicks":{"type":"number"},"cost":{"type":"string"},"sales":{"type":"string","description":"Total attributed sales: click plus view. Sponsored Products has no view attribution, so there it equals sales_clicks. acos and roas are computed on this total. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_clicks":{"type":"string","description":"Sales attributed to ad clicks only. For Sponsored Brands and Sponsored Display, sales minus this is what view attribution added. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"sales_views":{"type":"string","description":"Sales attributed to ad views: sales minus sales_clicks. Always 0 on Sponsored Products."},"orders":{"type":"number","description":"Total attributed orders: click plus view on Sponsored Brands and Sponsored Display; on Sponsored Products it equals click orders. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"units":{"type":"number","description":"Units sold attributed to ad clicks only; view-attributed units are not included. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"ctr":{"nullable":true,"type":"number"},"cpc":{"nullable":true,"type":"string"},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"description":"Click-attributed orders divided by clicks. View-attributed orders are left out, since they could push the rate above 1; orders itself is the total.","type":"number"}},"required":["object","search_term","query","target","campaign","ad_group","ad_product","connection","country","currency","impressions","clicks","cost","sales","sales_clicks","sales_views","orders","units","ctr","cpc","acos","roas","conversion_rate"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/clusters":{"get":{"summary":"List the authenticated account's keyword clusters","tags":["clusters"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the cluster name and its positive and negative keywords. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"notes":{"nullable":true,"type":"string"},"positiveKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"negativeKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"protected":{"type":"boolean"},"productCount":{"type":"number"},"products":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"cost":{"nullable":true,"description":"Product and shipping cost in force today, the same that feeds the P&L. `null` for advertising products and on plans without product cost (Free and Guru).","type":"object","properties":{"cogs":{"nullable":true,"description":"Unit cost of the product in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false},"shipping":{"nullable":true,"description":"Unit shipping cost in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false}},"required":["cogs","shipping"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","cost","createdAt","updatedAt"],"additionalProperties":false}}]},"prompts":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","notes","positiveKeywords","negativeKeywords","protected","productCount","prompts","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a keyword cluster","tags":["clusters"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Name shown in the Epinium clusters table."},"positiveKeywords":{"description":"Keywords the products should rank or advertise for, up to 100.","maxItems":100,"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string","minLength":1,"maxLength":80,"pattern":"^(?![-.])(?!.*\\s-)(?!.*[-+]\\s)(?!.*[-+.]$)[0-9a-zA-Z®ÁÉÍÑÓÚÜáéíñóúüÄÖŒßäöÀÂÆÇÈÊËÎÏÔÙÛŸàâæçèéêëîïôùûÿœ　-ゟ゠-ヿ一-鿿＀-￯ &+\\-[\\]'\".\\\\]{1,80}$","description":"The keyword as a shopper would type it. Stored lowercased; duplicates within the same list are merged."},"language":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","description":"Language-country code of the keyword, like es-ES, en-GB or de-DE."},"epiniumScore":{"description":"Relevance from 1 (weak) to 5 (core keyword), the same stars the app shows. Omit to leave it unrated.","type":"integer","minimum":1,"maximum":5},"purpose":{"description":"What the keyword is for: SEO (listing content), PPC (advertising targets) or both. A new keyword defaults to both.","minItems":1,"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language"],"additionalProperties":false}},"negativeKeywords":{"description":"Keywords to keep away from, up to 50.","maxItems":50,"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string","minLength":1,"maxLength":80,"pattern":"^(?![-.])(?!.*\\s-)(?!.*[-+]\\s)(?!.*[-+.]$)[0-9a-zA-Z®ÁÉÍÑÓÚÜáéíñóúüÄÖŒßäöÀÂÆÇÈÊËÎÏÔÙÛŸàâæçèéêëîïôùûÿœ　-ゟ゠-ヿ一-鿿＀-￯ &+\\-[\\]'\".\\\\]{1,80}$","description":"The keyword as a shopper would type it. Stored lowercased; duplicates within the same list are merged."},"language":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","description":"Language-country code of the keyword, like es-ES, en-GB or de-DE."},"epiniumScore":{"description":"Relevance from 1 (weak) to 5 (core keyword), the same stars the app shows. Omit to leave it unrated.","type":"integer","minimum":1,"maximum":5},"purpose":{"description":"What the keyword is for: SEO (listing content), PPC (advertising targets) or both. A new keyword defaults to both.","minItems":1,"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language"],"additionalProperties":false}},"products":{"description":"Ids of catalog products (`/v1/products` with `type` seller or vendor) the cluster groups. Every id must belong to the account; advertising products (`type` adv) are refused.","maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"prompts":{"description":"Ids of custom prompts of the account (from `/v1/prompts`) that the SEO content generation of the cluster products follows. An id that does not belong to the account is refused.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"notes":{"nullable":true,"type":"string"},"positiveKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"negativeKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"protected":{"type":"boolean"},"productCount":{"type":"number"},"products":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"cost":{"nullable":true,"description":"Product and shipping cost in force today, the same that feeds the P&L. `null` for advertising products and on plans without product cost (Free and Guru).","type":"object","properties":{"cogs":{"nullable":true,"description":"Unit cost of the product in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false},"shipping":{"nullable":true,"description":"Unit shipping cost in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false}},"required":["cogs","shipping"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","cost","createdAt","updatedAt"],"additionalProperties":false}}]},"prompts":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","notes","positiveKeywords","negativeKeywords","protected","productCount","prompts","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/clusters/{id}":{"get":{"tags":["clusters"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"notes":{"nullable":true,"type":"string"},"positiveKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"negativeKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"protected":{"type":"boolean"},"productCount":{"type":"number"},"products":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"cost":{"nullable":true,"description":"Product and shipping cost in force today, the same that feeds the P&L. `null` for advertising products and on plans without product cost (Free and Guru).","type":"object","properties":{"cogs":{"nullable":true,"description":"Unit cost of the product in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false},"shipping":{"nullable":true,"description":"Unit shipping cost in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false}},"required":["cogs","shipping"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","cost","createdAt","updatedAt"],"additionalProperties":false}}]},"prompts":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","notes","positiveKeywords","negativeKeywords","protected","productCount","prompts","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Add or remove keywords and products of a cluster, or rename it","tags":["clusters"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name.","type":"string","minLength":1,"maxLength":200},"addPositiveKeywords":{"description":"Positive keywords to add or update, matched by text. The list cannot exceed 100 afterwards.","maxItems":100,"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string","minLength":1,"maxLength":80,"pattern":"^(?![-.])(?!.*\\s-)(?!.*[-+]\\s)(?!.*[-+.]$)[0-9a-zA-Z®ÁÉÍÑÓÚÜáéíñóúüÄÖŒßäöÀÂÆÇÈÊËÎÏÔÙÛŸàâæçèéêëîïôùûÿœ　-ゟ゠-ヿ一-鿿＀-￯ &+\\-[\\]'\".\\\\]{1,80}$","description":"The keyword as a shopper would type it. Stored lowercased; duplicates within the same list are merged."},"language":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","description":"Language-country code of the keyword, like es-ES, en-GB or de-DE."},"epiniumScore":{"description":"Relevance from 1 (weak) to 5 (core keyword), the same stars the app shows. Omit to leave it unrated.","type":"integer","minimum":1,"maximum":5},"purpose":{"description":"What the keyword is for: SEO (listing content), PPC (advertising targets) or both. A new keyword defaults to both.","minItems":1,"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language"],"additionalProperties":false}},"removePositiveKeywords":{"description":"Texts of positive keywords to remove. Unknown texts are ignored.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"addNegativeKeywords":{"description":"Negative keywords to add or update, matched by text. The list cannot exceed 50 afterwards.","maxItems":50,"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string","minLength":1,"maxLength":80,"pattern":"^(?![-.])(?!.*\\s-)(?!.*[-+]\\s)(?!.*[-+.]$)[0-9a-zA-Z®ÁÉÍÑÓÚÜáéíñóúüÄÖŒßäöÀÂÆÇÈÊËÎÏÔÙÛŸàâæçèéêëîïôùûÿœ　-ゟ゠-ヿ一-鿿＀-￯ &+\\-[\\]'\".\\\\]{1,80}$","description":"The keyword as a shopper would type it. Stored lowercased; duplicates within the same list are merged."},"language":{"type":"string","pattern":"^[a-z]{2}-[A-Z]{2}$","description":"Language-country code of the keyword, like es-ES, en-GB or de-DE."},"epiniumScore":{"description":"Relevance from 1 (weak) to 5 (core keyword), the same stars the app shows. Omit to leave it unrated.","type":"integer","minimum":1,"maximum":5},"purpose":{"description":"What the keyword is for: SEO (listing content), PPC (advertising targets) or both. A new keyword defaults to both.","minItems":1,"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language"],"additionalProperties":false}},"removeNegativeKeywords":{"description":"Texts of negative keywords to remove. Unknown texts are ignored.","maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"addProducts":{"description":"Ids of catalog products (`type` seller or vendor) to add. Every id must belong to the account; advertising products are refused and ids already in the cluster are ignored.","maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"removeProducts":{"description":"Ids of catalog products to take out of the cluster.","maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"addPrompts":{"description":"Ids of custom prompts of the account (from `/v1/prompts`) that the SEO content generation of the cluster products follows. An id that does not belong to the account is refused. Ids already in the cluster are ignored.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"removePrompts":{"description":"Ids of prompts to take out of the cluster. The prompts themselves are not deleted.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"notes":{"nullable":true,"type":"string"},"positiveKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"negativeKeywords":{"type":"array","items":{"type":"object","properties":{"keywordText":{"type":"string"},"language":{"type":"string"},"epiniumScore":{"nullable":true,"type":"number"},"purpose":{"type":"array","items":{"type":"string","enum":["SEO","PPC"]}}},"required":["keywordText","language","epiniumScore","purpose"],"additionalProperties":false}},"protected":{"type":"boolean"},"productCount":{"type":"number"},"products":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"asin":{"type":"string"},"sku":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"ean":{"nullable":true,"type":"string"},"upc":{"nullable":true,"type":"string"},"gtin":{"nullable":true,"type":"string"},"platform":{"type":"string","enum":["amazon"]},"type":{"type":"string","enum":["seller","vendor","adv"]},"active":{"type":"boolean"},"connection":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["seller","vendor","adv-profile","shopify","woocommerce"]},"name":{"type":"string"},"active":{"type":"boolean"},"countries":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","type","name","active","countries","createdAt"],"additionalProperties":false}]},"country":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"code":{"type":"string"},"name":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["id","code","name"],"additionalProperties":false}]},"brand":{"nullable":true,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}]},"cost":{"nullable":true,"description":"Product and shipping cost in force today, the same that feeds the P&L. `null` for advertising products and on plans without product cost (Free and Guru).","type":"object","properties":{"cogs":{"nullable":true,"description":"Unit cost of the product in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false},"shipping":{"nullable":true,"description":"Unit shipping cost in force today; `null` when it has none.","type":"object","properties":{"unit_cost":{"type":"number"},"currency":{"type":"string"},"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source":{"type":"string","enum":["manual","csv","purchase","erp","api"],"description":"Where the cost came from: `manual` (the product page), `csv` (a file import), `api` (`POST /v1/products/:id/costs` or the MCP), `purchase` (average cost of purchases), `erp` (a management system)."}},"required":["unit_cost","currency","valid_from","source"],"additionalProperties":false}},"required":["cogs","shipping"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","asin","sku","title","ean","upc","gtin","platform","type","active","connection","country","cost","createdAt","updatedAt"],"additionalProperties":false}}]},"prompts":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","notes","positiveKeywords","negativeKeywords","protected","productCount","prompts","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a keyword cluster","tags":["clusters"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"}},"required":["id","result","error"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/brand-identities":{"get":{"summary":"List the authenticated account's brand identities","tags":["brand-identities"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the brand name and category. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"category":{"nullable":true,"type":"string"},"brand_urls":{"type":"array","items":{"type":"string"}},"competitor_urls":{"type":"array","items":{"type":"string"}},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Brand or seller name of the competitor."},"url":{"description":"Its website or Amazon store page, a full http(s) URL.","type":"string","maxLength":2048,"format":"uri"},"asins":{"description":"ASINs of its products that compete with the brand, up to 20.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{10}$","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`."}},"threat":{"description":"Threat level with its reason. Leave it out when there is no evidence yet.","type":"object","properties":{"level":{"type":"string","enum":["low","medium","high"],"description":"How dangerous it is for the brand."},"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Why, citing what was seen: shared search terms, ASIN targets, Buy Box losses, price, reviews."}},"required":["level","reason"],"additionalProperties":false},"price_position":{"description":"Its price compared with the brand's.","type":"string","enum":["below","similar","above"]}},"required":["name"],"additionalProperties":false},"description":"Competitor profiles. Empty on brands saved before them, whose competitors are only in `competitor_urls`."},"observations":{"type":"string","description":"Free notes about the brand (tone, audience, words to use or avoid), as plain text: a blank line separates paragraphs. Empty when there are none."},"product_brand_ids":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"description":"Ids of catalog brands (`/v1/product-brands`) this brand identity covers."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","category","brand_urls","competitor_urls","competitors","observations","product_brand_ids","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a brand identity","tags":["brand-identities"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Name of the brand."},"category":{"description":"Category or sector of the brand.","type":"string","maxLength":200},"brand_urls":{"description":"Websites of the brand itself (store, social profiles), up to 20. Each one a full http(s) URL.","maxItems":20,"type":"array","items":{"type":"string","maxLength":2048,"format":"uri"}},"competitor_urls":{"description":"Websites or Amazon pages of competitors, up to 50. Each one a full http(s) URL.","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048,"format":"uri"}},"competitors":{"description":"Competitor profiles, up to 50: name, web or ASINs, threat level with its reason and price position. Independent of `competitor_urls`.","maxItems":50,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Brand or seller name of the competitor."},"url":{"description":"Its website or Amazon store page, a full http(s) URL.","type":"string","maxLength":2048,"format":"uri"},"asins":{"description":"ASINs of its products that compete with the brand, up to 20.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{10}$","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`."}},"threat":{"description":"Threat level with its reason. Leave it out when there is no evidence yet.","type":"object","properties":{"level":{"type":"string","enum":["low","medium","high"],"description":"How dangerous it is for the brand."},"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Why, citing what was seen: shared search terms, ASIN targets, Buy Box losses, price, reviews."}},"required":["level","reason"],"additionalProperties":false},"price_position":{"description":"Its price compared with the brand's.","type":"string","enum":["below","similar","above"]}},"required":["name"],"additionalProperties":false}},"observations":{"description":"Free notes about the brand (tone, audience, words to use or avoid), as PLAIN TEXT up to 5000 characters: HTML is stored escaped, never as markup. A blank line starts a new paragraph.","type":"string","maxLength":5000},"product_brand_ids":{"description":"Ids of catalog brands (from `/v1/product-brands`) this brand identity covers, up to 50. An unknown id is refused with 400.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"category":{"nullable":true,"type":"string"},"brand_urls":{"type":"array","items":{"type":"string"}},"competitor_urls":{"type":"array","items":{"type":"string"}},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Brand or seller name of the competitor."},"url":{"description":"Its website or Amazon store page, a full http(s) URL.","type":"string","maxLength":2048,"format":"uri"},"asins":{"description":"ASINs of its products that compete with the brand, up to 20.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{10}$","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`."}},"threat":{"description":"Threat level with its reason. Leave it out when there is no evidence yet.","type":"object","properties":{"level":{"type":"string","enum":["low","medium","high"],"description":"How dangerous it is for the brand."},"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Why, citing what was seen: shared search terms, ASIN targets, Buy Box losses, price, reviews."}},"required":["level","reason"],"additionalProperties":false},"price_position":{"description":"Its price compared with the brand's.","type":"string","enum":["below","similar","above"]}},"required":["name"],"additionalProperties":false},"description":"Competitor profiles. Empty on brands saved before them, whose competitors are only in `competitor_urls`."},"observations":{"type":"string","description":"Free notes about the brand (tone, audience, words to use or avoid), as plain text: a blank line separates paragraphs. Empty when there are none."},"product_brand_ids":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"description":"Ids of catalog brands (`/v1/product-brands`) this brand identity covers."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","category","brand_urls","competitor_urls","competitors","observations","product_brand_ids","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/brand-identities/{id}":{"get":{"tags":["brand-identities"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"category":{"nullable":true,"type":"string"},"brand_urls":{"type":"array","items":{"type":"string"}},"competitor_urls":{"type":"array","items":{"type":"string"}},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Brand or seller name of the competitor."},"url":{"description":"Its website or Amazon store page, a full http(s) URL.","type":"string","maxLength":2048,"format":"uri"},"asins":{"description":"ASINs of its products that compete with the brand, up to 20.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{10}$","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`."}},"threat":{"description":"Threat level with its reason. Leave it out when there is no evidence yet.","type":"object","properties":{"level":{"type":"string","enum":["low","medium","high"],"description":"How dangerous it is for the brand."},"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Why, citing what was seen: shared search terms, ASIN targets, Buy Box losses, price, reviews."}},"required":["level","reason"],"additionalProperties":false},"price_position":{"description":"Its price compared with the brand's.","type":"string","enum":["below","similar","above"]}},"required":["name"],"additionalProperties":false},"description":"Competitor profiles. Empty on brands saved before them, whose competitors are only in `competitor_urls`."},"observations":{"type":"string","description":"Free notes about the brand (tone, audience, words to use or avoid), as plain text: a blank line separates paragraphs. Empty when there are none."},"product_brand_ids":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"description":"Ids of catalog brands (`/v1/product-brands`) this brand identity covers."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","category","brand_urls","competitor_urls","competitors","observations","product_brand_ids","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Change the name, category, URLs, observations or catalog brands of a brand identity","tags":["brand-identities"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name.","type":"string","minLength":1,"maxLength":200},"category":{"description":"New category. An empty string clears it.","type":"string","maxLength":200},"brand_urls":{"description":"Websites of the brand itself (store, social profiles), up to 20. Each one a full http(s) URL. Replaces the whole list.","maxItems":20,"type":"array","items":{"type":"string","maxLength":2048,"format":"uri"}},"competitor_urls":{"description":"Websites or Amazon pages of competitors, up to 50. Each one a full http(s) URL. Replaces the whole list.","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048,"format":"uri"}},"competitors":{"description":"Competitor profiles, up to 50: name, web or ASINs, threat level with its reason and price position. Independent of `competitor_urls`. Replaces the whole list.","maxItems":50,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Brand or seller name of the competitor."},"url":{"description":"Its website or Amazon store page, a full http(s) URL.","type":"string","maxLength":2048,"format":"uri"},"asins":{"description":"ASINs of its products that compete with the brand, up to 20.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{10}$","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`."}},"threat":{"description":"Threat level with its reason. Leave it out when there is no evidence yet.","type":"object","properties":{"level":{"type":"string","enum":["low","medium","high"],"description":"How dangerous it is for the brand."},"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Why, citing what was seen: shared search terms, ASIN targets, Buy Box losses, price, reviews."}},"required":["level","reason"],"additionalProperties":false},"price_position":{"description":"Its price compared with the brand's.","type":"string","enum":["below","similar","above"]}},"required":["name"],"additionalProperties":false}},"observations":{"description":"Free notes about the brand (tone, audience, words to use or avoid), as PLAIN TEXT up to 5000 characters: HTML is stored escaped, never as markup. A blank line starts a new paragraph. Replaces the current notes; an empty string clears them.","type":"string","maxLength":5000},"product_brand_ids":{"description":"Ids of catalog brands (from `/v1/product-brands`) this brand identity covers, up to 50. An unknown id is refused with 400. Replaces the whole list.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"category":{"nullable":true,"type":"string"},"brand_urls":{"type":"array","items":{"type":"string"}},"competitor_urls":{"type":"array","items":{"type":"string"}},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Brand or seller name of the competitor."},"url":{"description":"Its website or Amazon store page, a full http(s) URL.","type":"string","maxLength":2048,"format":"uri"},"asins":{"description":"ASINs of its products that compete with the brand, up to 20.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{10}$","description":"Amazon ASIN: 10 uppercase letters or digits, e.g. `B08GPHNSCW`."}},"threat":{"description":"Threat level with its reason. Leave it out when there is no evidence yet.","type":"object","properties":{"level":{"type":"string","enum":["low","medium","high"],"description":"How dangerous it is for the brand."},"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Why, citing what was seen: shared search terms, ASIN targets, Buy Box losses, price, reviews."}},"required":["level","reason"],"additionalProperties":false},"price_position":{"description":"Its price compared with the brand's.","type":"string","enum":["below","similar","above"]}},"required":["name"],"additionalProperties":false},"description":"Competitor profiles. Empty on brands saved before them, whose competitors are only in `competitor_urls`."},"observations":{"type":"string","description":"Free notes about the brand (tone, audience, words to use or avoid), as plain text: a blank line separates paragraphs. Empty when there are none."},"product_brand_ids":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"description":"Ids of catalog brands (`/v1/product-brands`) this brand identity covers."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","category","brand_urls","competitor_urls","competitors","observations","product_brand_ids","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-updates/prepare":{"post":{"summary":"Find the SKUs of a file and the attributes they can take","tags":["listing-updates"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"marketplace":{"description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`). Required unless a column has `marketplace: true` (or `marketplace_column` in `prepare`); with that column it is ignored.","type":"string","minLength":2,"maxLength":40},"key_type":{"description":"What identifies each row: `sku` (default), `asin` or `ean`.","type":"string","enum":["sku","asin","ean"]},"file_id":{"type":"string","pattern":"^[0-9a-f]{24}$","description":"The `file_id` of a file uploaded with the upload box."},"key_column":{"description":"With `file_id`: the header of the column that holds the identifiers.","type":"string","minLength":1,"maxLength":200},"marketplace_column":{"description":"With `file_id`: the header of the column that holds the country of each row.","type":"string","minLength":1,"maxLength":200},"vendor_code_column":{"description":"With `file_id`: the header of the column that holds the vendor code of each row.","type":"string","minLength":1,"maxLength":200},"identifiers":{"description":"Without a file: every identifier in it, as written there.","minItems":1,"maxItems":2000,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"marketplace_id":{"type":"string"},"found":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"not_found":{"type":"array","items":{"type":"string"}},"not_found_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"invalid_identifiers":{"type":"array","items":{"type":"string"}},"multiple":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"items":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"skus":{"type":"array","items":{"type":"string"}}},"required":["identifier","skus"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"vendor_code_groups":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"vendor_codes":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["marketplace_id","vendor_codes","rows","row_numbers","skus"],"additionalProperties":false}},"product_types":{"type":"array","items":{"type":"object","properties":{"product_type":{"type":"string"},"account_type":{"type":"string","enum":["seller","vendor"]},"skus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"schema_status":{"type":"string","enum":["ready","downloading","failed","unavailable"],"description":"ready: rows of this product type can be validated. downloading: Epinium is fetching its schema from Amazon; validate in a minute. failed: Amazon did not return it. unavailable: Epinium cannot fetch it from here."}},"required":["product_type","account_type","skus","schema_status"],"additionalProperties":false}},"searched":{"type":"object","properties":{"marketplace_id":{"type":"string"},"seller_connections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["marketplace_id","seller_connections"],"additionalProperties":false},"not_found_elsewhere":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"marketplace":{"type":"string"},"skus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["marketplace_id","marketplace","skus"],"additionalProperties":false}},"candidates":{"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string"},"title":{"type":"string"},"present_in":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"multiple":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"label":{"type":"string"},"kind":{"type":"string"},"options":{"type":"array","items":{"type":"string"}}},"required":["path","label","kind"],"additionalProperties":false}},"offer_fields":{"type":"array","items":{"type":"object","properties":{"audience":{"type":"string","enum":["ALL","B2B"]},"field":{"type":"string","enum":["price","min","max","sale_price","sale_start","sale_end"]},"label":{"type":"string"}},"required":["audience","field","label"],"additionalProperties":false}}},"required":["attribute","title","present_in"],"additionalProperties":false}},"marketplaces":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"found":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"not_found":{"type":"array","items":{"type":"string"}},"not_found_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"invalid_identifiers":{"type":"array","items":{"type":"string"}},"multiple":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"items":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"skus":{"type":"array","items":{"type":"string"}}},"required":["identifier","skus"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"vendor_code_groups":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"vendor_codes":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["marketplace_id","vendor_codes","rows","row_numbers","skus"],"additionalProperties":false}},"product_types":{"type":"array","items":{"type":"object","properties":{"product_type":{"type":"string"},"account_type":{"type":"string","enum":["seller","vendor"]},"skus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"schema_status":{"type":"string","enum":["ready","downloading","failed","unavailable"],"description":"ready: rows of this product type can be validated. downloading: Epinium is fetching its schema from Amazon; validate in a minute. failed: Amazon did not return it. unavailable: Epinium cannot fetch it from here."}},"required":["product_type","account_type","skus","schema_status"],"additionalProperties":false}},"searched":{"type":"object","properties":{"marketplace_id":{"type":"string"},"seller_connections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["marketplace_id","seller_connections"],"additionalProperties":false},"not_found_elsewhere":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"marketplace":{"type":"string"},"skus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["marketplace_id","marketplace","skus"],"additionalProperties":false}},"marketplace":{"type":"string"},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["marketplace_id","found","not_found","not_found_total","invalid_identifiers","multiple","product_types","searched","not_found_elsewhere","marketplace","rows"],"additionalProperties":false}},"unrecognized_marketplaces":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["value","rows","row_numbers"],"additionalProperties":false}},"file":{"type":"object","properties":{"name":{"type":"string"},"sheet":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sample_rows":{"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"string","nullable":true,"enum":[null]}]}}}},"required":["name","sheet","headers","row_count","sample_rows"],"additionalProperties":false}},"required":["candidates"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-updates/validate":{"post":{"summary":"Convert and validate listing attribute changes, without sending them to Amazon","tags":["listing-updates"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"marketplace":{"description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`). Required unless a column has `marketplace: true` (or `marketplace_column` in `prepare`); with that column it is ignored.","type":"string","minLength":2,"maxLength":40},"key_type":{"description":"What identifies each row: `sku` (default), `asin` or `ean`.","type":"string","enum":["sku","asin","ean"]},"columns":{"minItems":2,"maxItems":60,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"key":{"description":"True for the one column that holds the identifiers (SKU, ASIN or EAN).","type":"boolean"},"attribute":{"description":"Amazon attribute this column fills. Omit it to ignore the column.","type":"string","minLength":1,"maxLength":120},"marketplace":{"description":"True for the column that holds the country of each row. At most one column has it.","type":"boolean"},"vendor_code":{"description":"True for the column that holds the vendor code of each row (vendor accounts). At most one column has it.","type":"boolean"},"unit":{"description":"Unit of the values (`kg`, `g`, `cm`, `ml`...). Read from a header like \"Weight (kg)\" when omitted.","type":"string","maxLength":20},"position":{"description":"Entry of a multi-valued attribute this column fills: \"Bullet 2\" is position 2.","type":"integer","minimum":1,"maximum":20},"path":{"description":"Sub-field of the attribute this column fills, from `fields[].path` in `prepare`: `[\"cell_composition\"]` or `[\"weight\"]` in `battery`. Without it the column fills the attribute `value`.","minItems":1,"maxItems":6,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"values":{"description":"Fixes for values of this column, applied to every row: `{\"Portugall\": \"Portugal\"}`.","type":"object","additionalProperties":{"type":"string","maxLength":5000}},"offer":{"description":"Seller price column, by audience. Set it instead of `attribute`. Not used on Vendor accounts (reported as `vendor_price`).","type":"object","properties":{"audience":{"type":"string","enum":["ALL","B2B"],"description":"`ALL` = the price every buyer sees; `B2B` = the business-buyer price."},"field":{"type":"string","enum":["price","min","max","sale_price","sale_start","sale_end"],"description":"Which value of that audience the column holds: the price, its minimum or maximum, or the sale price and its start and end dates."}},"required":["audience","field"],"additionalProperties":false},"clear":{"description":"Set only after the person explicitly confirmed that an empty cell in this column deletes the value from the listing. Without it, empty cells leave the value alone (see `offer_clears` in `validate`).","type":"boolean"},"date_order":{"description":"Order of the day and month in the date cells of this column when they are written as numbers: `dmy` (day first, the default) or `mdy` (month first).","type":"string","enum":["dmy","mdy"]}},"required":["name"],"additionalProperties":false}},"file_id":{"type":"string","pattern":"^[0-9a-f]{24}$","description":"The `file_id` of a file uploaded with the upload box."},"from_row":{"description":"With `file_id`: first data row to read (0 = the first one). Use `next_row` from the previous answer.","type":"integer","minimum":0,"maximum":9007199254740991},"rows":{"description":"Without a file: one array per product, values in the same order as `columns`.","minItems":1,"maxItems":30,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string","maxLength":5000},{"type":"number"},{"type":"boolean"},{"type":"string","nullable":true,"enum":[null]}]}}}},"required":["columns"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"applied":{"type":"boolean","enum":[false],"description":"Always false here: validating saves nothing. `apply` saves the rows as pending changes in Epinium."},"next_row":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"summary":{"type":"object","properties":{"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"listings":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ready":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"blocked":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"not_found":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"no_changes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"with_warnings":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"with_amazon_errors":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"direct":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cascade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["rows","listings","ready","blocked","not_found","no_changes","with_warnings","with_amazon_errors","direct","cascade"],"additionalProperties":false},"cascades":{"type":"array","items":{"type":"object","properties":{"cascade_id":{"type":"string"},"product_type":{"type":"string"},"account_type":{"type":"string","enum":["seller","vendor"]},"attribute":{"type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"string","nullable":true,"enum":[null]}]},"proposal_hash":{"nullable":true,"type":"string"},"proposal":{"nullable":true,"type":"object","additionalProperties":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["cascade_id","product_type","account_type","attribute","value","proposal_hash","proposal","rows","row_numbers","skus"],"additionalProperties":false}},"blocking":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"column":{"type":"string"},"attribute":{"nullable":true,"type":"string"},"code":{"type":"string"},"value":{"type":"string"},"message":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["attribute","code","message","rows","row_numbers","skus"],"additionalProperties":false}},"items":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"status":{"type":"string","enum":["not_found"]}},"required":["identifier","status"],"additionalProperties":false}},"multiple":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"items":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"skus":{"type":"array","items":{"type":"string"}}},"required":["identifier","skus"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"vendor_code_groups":{"description":"Rows whose identifier matches listings under several vendor codes in a country. They are validated and counted in `summary`, but `apply` leaves them out unless their country and combination come in `confirmed_multiple`.","type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"vendor_codes":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["marketplace_id","vendor_codes","rows","row_numbers","skus"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"attribute":{"type":"string"},"code":{"type":"string"},"value":{"type":"string"},"message":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["attribute","code","message","rows","row_numbers","skus"],"additionalProperties":false}},"not_applicable":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"attribute":{"type":"string"},"reason":{"type":"string","enum":["not_in_product_type","not_editable","vendor_price"]},"product_types":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["column","attribute","reason","product_types","rows"],"additionalProperties":false}},"amazon_errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skus":{"type":"array","items":{"type":"string"}}},"required":["code","message","attributes","rows","skus"],"additionalProperties":false}},"offer_clears":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"audience":{"type":"string","enum":["ALL","B2B"]},"field":{"type":"string","enum":["price","min","max","sale_price","sale_start","sale_end"]},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["column","audience","field","rows","row_numbers","skus"],"additionalProperties":false},"description":"Price columns with empty cells on products that have that value: ask whether they delete it (`clear: true`) or leave it alone."},"sample_patches":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"product_type":{"type":"string"},"patches":{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","replace"]},"path":{"type":"string"},"value":{"type":"array","items":{}}},"required":["op","path","value"],"additionalProperties":false}}},"required":["sku","product_type","patches"],"additionalProperties":false}},"marketplaces":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"object","properties":{"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"listings":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ready":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"blocked":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"not_found":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"no_changes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"with_warnings":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"with_amazon_errors":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"direct":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cascade":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["rows","listings","ready","blocked","not_found","no_changes","with_warnings","with_amazon_errors","direct","cascade"],"additionalProperties":false},"cascades":{"type":"array","items":{"type":"object","properties":{"cascade_id":{"type":"string"},"product_type":{"type":"string"},"account_type":{"type":"string","enum":["seller","vendor"]},"attribute":{"type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"string","nullable":true,"enum":[null]}]},"proposal_hash":{"nullable":true,"type":"string"},"proposal":{"nullable":true,"type":"object","additionalProperties":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["cascade_id","product_type","account_type","attribute","value","proposal_hash","proposal","rows","row_numbers","skus"],"additionalProperties":false}},"blocking":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"column":{"type":"string"},"attribute":{"nullable":true,"type":"string"},"code":{"type":"string"},"value":{"type":"string"},"message":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["attribute","code","message","rows","row_numbers","skus"],"additionalProperties":false}},"items":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"status":{"type":"string","enum":["not_found"]}},"required":["identifier","status"],"additionalProperties":false}},"multiple":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"items":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"skus":{"type":"array","items":{"type":"string"}}},"required":["identifier","skus"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"vendor_code_groups":{"description":"Rows whose identifier matches listings under several vendor codes in a country. They are validated and counted in `summary`, but `apply` leaves them out unless their country and combination come in `confirmed_multiple`.","type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"vendor_codes":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["marketplace_id","vendor_codes","rows","row_numbers","skus"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"attribute":{"type":"string"},"code":{"type":"string"},"value":{"type":"string"},"message":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["attribute","code","message","rows","row_numbers","skus"],"additionalProperties":false}},"not_applicable":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"attribute":{"type":"string"},"reason":{"type":"string","enum":["not_in_product_type","not_editable","vendor_price"]},"product_types":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["column","attribute","reason","product_types","rows"],"additionalProperties":false}},"amazon_errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skus":{"type":"array","items":{"type":"string"}}},"required":["code","message","attributes","rows","skus"],"additionalProperties":false}},"offer_clears":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"audience":{"type":"string","enum":["ALL","B2B"]},"field":{"type":"string","enum":["price","min","max","sale_price","sale_start","sale_end"]},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["column","audience","field","rows","row_numbers","skus"],"additionalProperties":false},"description":"Price columns with empty cells on products that have that value: ask whether they delete it (`clear: true`) or leave it alone."},"sample_patches":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"product_type":{"type":"string"},"patches":{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","replace"]},"path":{"type":"string"},"value":{"type":"array","items":{}}},"required":["op","path","value"],"additionalProperties":false}}},"required":["sku","product_type","patches"],"additionalProperties":false}},"marketplace_id":{"type":"string"},"marketplace":{"type":"string"}},"required":["summary","cascades","blocking","items","multiple","warnings","not_applicable","amazon_errors","offer_clears","sample_patches","marketplace_id","marketplace"],"additionalProperties":false}},"unrecognized_marketplaces":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["value","rows","row_numbers"],"additionalProperties":false}}},"required":["applied","next_row"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-updates/apply/{fileId}":{"get":{"description":"Poll this after `POST /v1/listing-updates/apply` until `state` is `applied` or `failed`. `result` says what was sent; `charge` what was reserved, charged and given back. `404` when the file was never applied.","summary":"State and result of applying a file, and what it charged","tags":["listing-updates"],"parameters":[{"name":"fileId","in":"path","description":"The `file_id` of a file uploaded with the upload box.","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"state":{"type":"string","enum":["queued","processing","applied","failed"],"description":"`queued` and `processing` while the worker saves the rows; `applied` when done; `failed` with `error` (the reserve is given back in full and it can be applied again; with other settings only if nothing was saved yet)."},"started_at":{"type":"string"},"finished_at":{"nullable":true,"type":"string"},"result":{"nullable":true,"type":"object","properties":{"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows of the file sent, each counted once: also a row whose cascade went to the task while the rest was saved directly, or whose ASIN or EAN matches several listings. This is what is charged."},"direct":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows of the file with changes saved directly as pending changes. A row split between the two counts here and in `to_task`."},"to_task":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows of the file with a cascade sent to the task: one nobody confirmed, or one missing data. Only the cascade goes there; the rest of the row is saved directly."},"bulk":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"rejected":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"column":{"type":"string"},"attribute":{"nullable":true,"type":"string"},"code":{"type":"string"},"value":{"type":"string"},"message":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["attribute","code","message","rows","row_numbers","skus"],"additionalProperties":false}},"duplicated_skus":{"type":"array","items":{"type":"string"}}},"required":["applied","direct","to_task","bulk","task","rejected","duplicated_skus"],"additionalProperties":false},"charge":{"type":"object","properties":{"state":{"type":"string","enum":["none","reserved","settled","refunded"],"description":"`reserved` at acceptance (file rows x price); `settled` when done (rows sent x price, the rest is given back); `refunded` if it failed."},"reserved":{"type":"number","description":"Credits reserved when the file was accepted."},"charged":{"type":"number","description":"Credits charged: rows sent x price. 0 until settled."},"refunded":{"type":"number","description":"Credits given back: the reserve minus what was charged."}},"required":["state","reserved","charged","refunded"],"additionalProperties":false},"error":{"nullable":true,"type":"string"},"publication":{"nullable":true,"description":"With `state` `applied`: what Amazon did with the listings of the changes saved directly, counted by listing. `null` before that.","type":"object","properties":{"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Listings saved and not sent yet: someone has to press Publish in Epinium."},"publishing":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Listings sent to Amazon and waiting for its answer."},"published":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Listings Amazon accepted."},"rejected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Listings Amazon refused. Their changes stay pending, with the errors in `rejections`."},"rejections":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"asin":{"nullable":true,"type":"string"},"vendor_code":{"nullable":true,"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}}},"required":["code","message","attributes"],"additionalProperties":false}}},"required":["sku","asin","vendor_code","errors"],"additionalProperties":false},"description":"Up to 50 rejected listings with what Amazon said, as it said it. `attributes` are the ones to fix: often attributes the file did not touch, which Amazon still checks when the listing is sent."}},"required":["pending","publishing","published","rejected","rejections"],"additionalProperties":false}},"required":["file_id","state","started_at","finished_at","result","charge","error","publication"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-updates/apply":{"post":{"description":"Accepts the file and saves its rows in the background; answers `202` with the state, to poll with `GET /v1/listing-updates/apply/{file_id}`. Every row is validated again and the valid ones are saved as pending changes (nothing is published to Amazon until someone presses Publish). Rows whose change opens a cascade (a value that makes other attributes mandatory, like batteries) go to a task for a person to review, unless their `cascade_id` is in `confirmed_cascades`; so do rows that only miss attributes a cascade makes mandatory. With a column marked `marketplace: true`, each row goes to its own country and `marketplace` is ignored; a cascade is confirmed in each country separately, because its `cascade_id` includes the country. Rows whose identifier matches listings under several vendor codes in a country (`vendor_code_groups` in `validate`) are saved only if that country and combination are in `confirmed_multiple`, never by default; the rest are rejected. Values are applied as written, in the language of the file. Only the last row of each identifier (per country and vendor code) counts. Billing: on acceptance the file rows x the row price are reserved (`402` if the balance does not cover it); when the work ends only the rows sent (`applied`) are charged and the rest is given back, all of it if it fails. Calling again with the same settings returns the current state; with other settings while it runs, after it was applied, or after a failed attempt that already saved part of it, `409`. A file that expires in less than 24 h is also `409`: saving its rows reads the file again later, so upload it again and apply the new `file_id`. A failed file can be applied again with the same settings and resumes where it stopped; rows a person already approved or rejected in its task are not created again.","summary":"Save the valid rows of an uploaded file as pending listing changes","tags":["listing-updates"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"marketplace":{"description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`). Required unless a column has `marketplace: true` (or `marketplace_column` in `prepare`); with that column it is ignored.","type":"string","minLength":2,"maxLength":40},"key_type":{"description":"What identifies each row: `sku` (default), `asin` or `ean`.","type":"string","enum":["sku","asin","ean"]},"columns":{"minItems":2,"maxItems":60,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"key":{"description":"True for the one column that holds the identifiers (SKU, ASIN or EAN).","type":"boolean"},"attribute":{"description":"Amazon attribute this column fills. Omit it to ignore the column.","type":"string","minLength":1,"maxLength":120},"marketplace":{"description":"True for the column that holds the country of each row. At most one column has it.","type":"boolean"},"vendor_code":{"description":"True for the column that holds the vendor code of each row (vendor accounts). At most one column has it.","type":"boolean"},"unit":{"description":"Unit of the values (`kg`, `g`, `cm`, `ml`...). Read from a header like \"Weight (kg)\" when omitted.","type":"string","maxLength":20},"position":{"description":"Entry of a multi-valued attribute this column fills: \"Bullet 2\" is position 2.","type":"integer","minimum":1,"maximum":20},"path":{"description":"Sub-field of the attribute this column fills, from `fields[].path` in `prepare`: `[\"cell_composition\"]` or `[\"weight\"]` in `battery`. Without it the column fills the attribute `value`.","minItems":1,"maxItems":6,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"values":{"description":"Fixes for values of this column, applied to every row: `{\"Portugall\": \"Portugal\"}`.","type":"object","additionalProperties":{"type":"string","maxLength":5000}},"offer":{"description":"Seller price column, by audience. Set it instead of `attribute`. Not used on Vendor accounts (reported as `vendor_price`).","type":"object","properties":{"audience":{"type":"string","enum":["ALL","B2B"],"description":"`ALL` = the price every buyer sees; `B2B` = the business-buyer price."},"field":{"type":"string","enum":["price","min","max","sale_price","sale_start","sale_end"],"description":"Which value of that audience the column holds: the price, its minimum or maximum, or the sale price and its start and end dates."}},"required":["audience","field"],"additionalProperties":false},"clear":{"description":"Set only after the person explicitly confirmed that an empty cell in this column deletes the value from the listing. Without it, empty cells leave the value alone (see `offer_clears` in `validate`).","type":"boolean"},"date_order":{"description":"Order of the day and month in the date cells of this column when they are written as numbers: `dmy` (day first, the default) or `mdy` (month first).","type":"string","enum":["dmy","mdy"]}},"required":["name"],"additionalProperties":false}},"file_id":{"type":"string","pattern":"^[0-9a-f]{24}$","description":"The `file_id` of a file uploaded with the upload box."},"title":{"description":"Title of the task for the rows that need a review. Defaults to the file name.","type":"string","minLength":1,"maxLength":200},"confirmed_cascades":{"description":"`cascade_id` values from `validate` that the person explicitly confirmed in this conversation, after being shown each configuration: product type, attribute = value, what the file brings for the cascade (`proposal`) and how many rows. Those cascades are saved directly as pending changes; the rest go to a task to review in Epinium. Never by default or by inference.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"confirmed_multiple":{"description":"Country and vendor code combinations from `vendor_code_groups` in `validate` that the person explicitly confirmed in this conversation, as they came back. Only those are saved directly; never by default or by inference.","maxItems":100,"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string","minLength":2,"maxLength":40},"vendor_codes":{"minItems":2,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}}},"required":["marketplace_id","vendor_codes"],"additionalProperties":false}}},"required":["columns","file_id"],"additionalProperties":false}}}},"responses":{"202":{"description":"202","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"state":{"type":"string","enum":["queued","processing","applied","failed"],"description":"`queued` and `processing` while the worker saves the rows; `applied` when done; `failed` with `error` (the reserve is given back in full and it can be applied again; with other settings only if nothing was saved yet)."},"started_at":{"type":"string"},"finished_at":{"nullable":true,"type":"string"},"result":{"nullable":true,"type":"object","properties":{"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows of the file sent, each counted once: also a row whose cascade went to the task while the rest was saved directly, or whose ASIN or EAN matches several listings. This is what is charged."},"direct":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows of the file with changes saved directly as pending changes. A row split between the two counts here and in `to_task`."},"to_task":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows of the file with a cascade sent to the task: one nobody confirmed, or one missing data. Only the cascade goes there; the rest of the row is saved directly."},"bulk":{"nullable":true,"type":"string"},"task":{"nullable":true,"type":"string"},"rejected":{"type":"array","items":{"type":"object","properties":{"marketplace_id":{"type":"string"},"column":{"type":"string"},"attribute":{"nullable":true,"type":"string"},"code":{"type":"string"},"value":{"type":"string"},"message":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"row_numbers":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"skus":{"type":"array","items":{"type":"string"}}},"required":["attribute","code","message","rows","row_numbers","skus"],"additionalProperties":false}},"duplicated_skus":{"type":"array","items":{"type":"string"}}},"required":["applied","direct","to_task","bulk","task","rejected","duplicated_skus"],"additionalProperties":false},"charge":{"type":"object","properties":{"state":{"type":"string","enum":["none","reserved","settled","refunded"],"description":"`reserved` at acceptance (file rows x price); `settled` when done (rows sent x price, the rest is given back); `refunded` if it failed."},"reserved":{"type":"number","description":"Credits reserved when the file was accepted."},"charged":{"type":"number","description":"Credits charged: rows sent x price. 0 until settled."},"refunded":{"type":"number","description":"Credits given back: the reserve minus what was charged."}},"required":["state","reserved","charged","refunded"],"additionalProperties":false},"error":{"nullable":true,"type":"string"},"publication":{"nullable":true,"description":"With `state` `applied`: what Amazon did with the listings of the changes saved directly, counted by listing. `null` before that.","type":"object","properties":{"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Listings saved and not sent yet: someone has to press Publish in Epinium."},"publishing":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Listings sent to Amazon and waiting for its answer."},"published":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Listings Amazon accepted."},"rejected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Listings Amazon refused. Their changes stay pending, with the errors in `rejections`."},"rejections":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"asin":{"nullable":true,"type":"string"},"vendor_code":{"nullable":true,"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}}},"required":["code","message","attributes"],"additionalProperties":false}}},"required":["sku","asin","vendor_code","errors"],"additionalProperties":false},"description":"Up to 50 rejected listings with what Amazon said, as it said it. `attributes` are the ones to fix: often attributes the file did not touch, which Amazon still checks when the listing is sent."}},"required":["pending","publishing","published","rejected","rejections"],"additionalProperties":false}},"required":["file_id","state","started_at","finished_at","result","charge","error","publication"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-files":{"post":{"summary":"Upload a spreadsheet of listing changes, kept for 7 days","tags":["listing-files"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"File name with its extension: .xlsx, .xls or .csv."},"content_base64":{"type":"string","minLength":1,"maxLength":11184815,"description":"The file, in base64."}},"required":["name","content_base64"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"name":{"type":"string"},"sheet":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"type":"string"}},"required":["file_id","name","sheet","headers","row_count","expires_at"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"summary":"List the spreadsheets of listing changes uploaded in the last 7 days, newest first","tags":["listing-files"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string"},"name":{"type":"string"},"sheet":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"type":"string"},"created_at":{"type":"string","description":"When the file was uploaded (ISO 8601)."},"apply_state":{"nullable":true,"description":"State of its `apply`; `null` if it was never applied.","type":"string","enum":["queued","processing","applied","failed"]}},"required":["file_id","name","sheet","headers","row_count","expires_at","created_at","apply_state"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-files/rows":{"post":{"description":"For changes the user writes instead of uploading a spreadsheet: one row per product, the identifier first. It returns the same `file_id` as an upload, to prepare, validate and apply it. The same rows again return the same file, unless it is being applied or was applied: then a new one. Requires `catalog:write`.","summary":"Store listing changes written in a chat (headers and rows) as a file, kept for 7 days","tags":["listing-files"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"A short name to recognise it in the list of files, like \"Material - 12 SKUs\". Without it, a readable default.","type":"string","maxLength":200},"headers":{"minItems":1,"maxItems":250,"type":"array","items":{"type":"string","maxLength":200},"description":"Column names, as the user called each thing. The first one is the column of identifiers (SKU, ASIN or EAN)."},"rows":{"minItems":1,"maxItems":5000,"type":"array","items":{"maxItems":250,"type":"array","items":{"anyOf":[{"type":"string","maxLength":10000},{"type":"number"},{"type":"boolean"},{"type":"string","nullable":true,"enum":[null]}]}},"description":"One array per product, values in the same order as `headers` and exactly as the user wrote them."}},"required":["headers","rows"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"name":{"type":"string"},"sheet":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"row_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"type":"string"}},"required":["file_id","name","sheet","headers","row_count","expires_at"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-images":{"post":{"summary":"Upload a product image for Amazon listings, kept for 30 days","tags":["listing-images"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"File name of the image, with its extension: .jpg, .png, .gif or .tif."},"content_base64":{"type":"string","minLength":1,"maxLength":11184815,"description":"The image, in base64."}},"required":["name","content_base64"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"media_location":{"type":"string"}},"required":["name","media_location"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-catalog/search":{"get":{"summary":"Find a product in the Amazon catalog by ASIN, EAN, UPC or GTIN","tags":["listing-drafts"],"parameters":[{"name":"connection","in":"query","description":"Seller or vendor connection of the account. A vendor connection gets no restrictions check: Amazon offers it to sellers only.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"marketplace","in":"query","description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`).","required":true,"schema":{"type":"string","minLength":2,"maxLength":40}},{"name":"identifier","in":"query","description":"The ASIN, EAN, UPC or GTIN to look for, or up to 20 of the same type separated by commas: they all go to Amazon in one call.","required":true,"schema":{"type":"string","pattern":"^[^,]{1,40}(,[^,]{1,40}){0,19}$"}},{"name":"identifier_type","in":"query","description":"What `identifier` is.","required":true,"schema":{"type":"string","enum":["ASIN","EAN","UPC","GTIN"]}},{"name":"condition","in":"query","description":"Condition of the offer, to check whether the account may sell it (`new_new` by default). Seller connections only.","schema":{"type":"string","maxLength":40}},{"name":"include_attributes","in":"query","description":"`\"true\"` adds to each match the `attributes` Amazon shows for it in this marketplace, in listing format. For a new vendor listing of a product the account does not have in another connection: only the products that still miss values, never all the products of the file by default.","schema":{"type":"string","enum":["true","false"]}},{"name":"attribute_names","in":"query","description":"Only with `include_attributes`: the attribute names to return, separated by commas, such as the ones `missing` lists in the validation. Without it every attribute comes back, about 3 KB per product.","schema":{"type":"string","maxLength":2000,"pattern":"^[a-z0-9_]+(,[a-z0-9_]+)*$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"asin":{"type":"string"},"identifier":{"description":"Which of the searched identifiers this match answers. Absent when the identifiers Amazon lists for the item include none of the searched ones: then it is tied to none of them, so search those identifiers one at a time.","type":"string"},"productType":{"type":"string"},"brand":{"type":"string"},"title":{"type":"string"},"parentAsins":{"type":"array","items":{"type":"string"},"description":"Parent of its variation family in this marketplace. An offer on this ASIN joins that family by itself."},"childAsinsCount":{"type":"number","description":"Variations under it, when the ASIN is itself a family parent."},"variationTheme":{"type":"string"},"restrictions":{"type":"array","items":{"type":"object","properties":{"conditionType":{"type":"string"},"reasons":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"reasonCode":{"description":"`APPROVAL_REQUIRED`, `ASIN_NOT_FOUND` or `NOT_ELIGIBLE`; `CHECK_FAILED` when Amazon could not be asked: search that ASIN again.","type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"resource":{"type":"string"},"title":{"type":"string"}},"required":["resource"],"additionalProperties":false}}},"required":["message","links"],"additionalProperties":false}}},"required":["reasons"],"additionalProperties":false},"description":"Empty when the account can sell it in that condition. Always empty with a vendor connection."},"attributes":{"description":"Only with `include_attributes`: the attributes of the catalog in this marketplace, as Amazon shows them. They can come from another seller or vendor and differ from what the account will upload.","type":"object","additionalProperties":{}}},"required":["asin","parentAsins","childAsinsCount","restrictions"],"additionalProperties":false}},"incomplete":{"type":"boolean","description":"`true` when Amazon found more matches than fit in one answer: search again, in a smaller batch, the identifiers that came back without a match."}},"required":["data","incomplete"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-product-types/search":{"get":{"summary":"Recommend the Amazon product type of a new product from its name","tags":["listing-drafts"],"parameters":[{"name":"connection","in":"query","description":"Seller or vendor connection of the account. A vendor connection creates whole listings with `productType`, never offers on an existing ASIN: Amazon does not support them for vendors.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"marketplace","in":"query","description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`).","required":true,"schema":{"type":"string","minLength":2,"maxLength":40}},{"name":"name","in":"query","description":"Name of the product, as the user would title it (for example \"Camiseta de algodón para hombre\").","required":true,"schema":{"type":"string","minLength":1,"maxLength":250}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The product type to send as `productType`."},"displayName":{"type":"string"}},"required":["name","displayName"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/amazon-shipping-templates":{"get":{"summary":"List the shipping templates of a seller account in one marketplace","tags":["listing-drafts"],"parameters":[{"name":"connection","in":"query","description":"Seller Central connection of the account. Vendor connections cannot create offers.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"marketplace","in":"query","description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`).","required":true,"schema":{"type":"string","minLength":2,"maxLength":40}},{"name":"refresh","in":"query","description":"`true` asks Amazon again even if the stored list is less than a day old, for a template created a moment ago.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The key to send as the `value` of `merchant_shipping_group`."},"name":{"type":"string","description":"Its name in Seller Central, to show to the user."}},"required":["id","name"],"additionalProperties":false}},"fetchedAt":{"type":"string","description":"When the list was read from Amazon."},"stale":{"type":"boolean","description":"`true` when Amazon did not answer and this is the stored list, more than a day old."}},"required":["data","fetchedAt","stale"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-drafts/validate":{"post":{"summary":"Validate a new offer on an existing ASIN, or a new product, against its schema and with Amazon, without saving anything","tags":["listing-drafts"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Seller or vendor connection of the account. A vendor connection creates whole listings with `productType`, never offers on an existing ASIN: Amazon does not support them for vendors."},"marketplace":{"type":"string","minLength":2,"maxLength":40,"description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`)."},"sku":{"type":"string","minLength":1,"maxLength":40,"description":"SKU of the new offer or product. Ask the user for it; if you suggest one, they confirm it."},"asin":{"description":"For an offer on a product that already exists on Amazon: its ASIN, as epinium_search_amazon_catalog returned it.","type":"string","pattern":"^[A-Z0-9]{10}$"},"productType":{"description":"For a product that is not on Amazon yet, instead of `asin`: its Amazon product type (for example SHIRT), as epinium_search_amazon_product_types recommended it.","type":"string","minLength":1},"vendor_code":{"description":"Vendor connections only: the vendor code to list under. Optional when the connection has a single one.","type":"string","minLength":1,"maxLength":20},"attributes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","additionalProperties":{}}},"description":"Attributes in Amazon listing format, each one an array of entries. For an offer: condition, price, quantity or fulfillment channel, for example `condition_type: [{ value: \"new_new\" }]`, `purchasable_offer: [{ currency: \"EUR\", our_price: [{ schedule: [{ value_with_tax: 19.99 }] }] }]` and `fulfillment_availability: [{ fulfillment_channel_code: \"DEFAULT\", quantity: 10 }]`; `merchant_suggested_asin` is filled from `asin`. For a new product, the whole listing. A parent of a variation family: `parentage_level: [{ value: \"parent\" }]`, `child_parent_sku_relationship: [{}]`, `variation_theme: [{ name }]` and the product facts, with no offer and no EAN. A child: `parentage_level: [{ value: \"child\" }]`, `child_parent_sku_relationship: [{ parent_sku }]`, the same `variation_theme` and its attributes, plus the brand, the EAN (`externally_assigned_product_identifier`) or the GTIN exemption, images and the offer."}},"required":["connection","marketplace","sku","attributes"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"attribute":{"nullable":true,"type":"string"},"message":{"type":"string"},"missing":{"description":"Attributes a rule of the schema requires and the offer lacks.","type":"array","items":{"type":"string"}},"suggestions":{"description":"For a value the schema does not accept: the closest accepted values.","type":"array","items":{"type":"object","properties":{"value":{},"label":{"type":"string"}},"required":["value","label"],"additionalProperties":false}}},"required":["attribute","message"],"additionalProperties":false},"description":"Problems found against the schema before asking Amazon. Amazon is only asked when there are none."},"missing":{"description":"Each attribute the schema requires and the listing lacks, once. Fill each one from the product's own title, bullet points, description and columns when they say it, then validate again: a value can make Amazon ask for more. Ask the user only what that content does not say, and never choose a legal declaration (dangerous goods, batteries, safety) for them.","type":"array","items":{"type":"object","properties":{"attribute":{"type":"string"},"title":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Path inside one entry of the attribute; `0` marks an entry of a nested array, as in `material.0.value`."},"label":{"type":"string"},"kind":{"type":"string"},"options":{"description":"The accepted values: send one `value` exactly.","type":"array","items":{"type":"object","properties":{"value":{},"label":{"type":"string"}},"required":["value","label"],"additionalProperties":false}},"optionsCount":{"description":"A list too long to send: send the value, and if it is not accepted the error brings the closest ones in `suggestions`.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["path","label","kind"],"additionalProperties":false},"description":"How to fill one entry of the attribute, field by field."}},"required":["attribute","title","fields"],"additionalProperties":false}},"amazon":{"type":"object","properties":{"status":{"type":"string","enum":["VALID","INVALID"]},"asin":{"description":"ASIN the offer would be attached to.","type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"severity":{"type":"string"},"attributeNames":{"type":"array","items":{"type":"string"}}},"required":["code","message","severity","attributeNames"],"additionalProperties":false}},"missing":{"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string"},"title":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Path inside one entry of the attribute; `0` marks an entry of a nested array, as in `material.0.value`."},"label":{"type":"string"},"kind":{"type":"string"},"options":{"description":"The accepted values: send one `value` exactly.","type":"array","items":{"type":"object","properties":{"value":{},"label":{"type":"string"}},"required":["value","label"],"additionalProperties":false}},"optionsCount":{"description":"A list too long to send: send the value, and if it is not accepted the error brings the closest ones in `suggestions`.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["path","label","kind"],"additionalProperties":false},"description":"How to fill one entry of the attribute, field by field."},"options":{"description":"The values of its first field with a list.","type":"array","items":{"type":"object","properties":{"value":{},"label":{"type":"string"}},"required":["value","label"],"additionalProperties":false}}},"required":["attribute","title","fields"],"additionalProperties":false},"description":"Attributes Amazon requires for this product and the listing lacks, for example `supplier_declared_dg_hz_regulation: [{ value: \"not_applicable\" }]`. Fill each one from the product's own title, bullet points, description and columns when they say it, then validate again: a value can make Amazon ask for more. Ask the user only what that content does not say, and never choose a legal declaration (dangerous goods, batteries, safety) for them."}},"required":["status","issues","missing"],"additionalProperties":false}},"required":["valid","errors"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-drafts":{"post":{"summary":"Save a new offer on an existing ASIN, or a new product, pending to publish from the app","tags":["listing-drafts"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Seller or vendor connection of the account. A vendor connection creates whole listings with `productType`, never offers on an existing ASIN: Amazon does not support them for vendors."},"marketplace":{"type":"string","minLength":2,"maxLength":40,"description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`)."},"sku":{"type":"string","minLength":1,"maxLength":40,"description":"SKU of the new offer or product. Ask the user for it; if you suggest one, they confirm it."},"asin":{"description":"For an offer on a product that already exists on Amazon: its ASIN, as epinium_search_amazon_catalog returned it.","type":"string","pattern":"^[A-Z0-9]{10}$"},"productType":{"description":"For a product that is not on Amazon yet, instead of `asin`: its Amazon product type (for example SHIRT), as epinium_search_amazon_product_types recommended it.","type":"string","minLength":1},"vendor_code":{"description":"Vendor connections only: the vendor code to list under. Optional when the connection has a single one.","type":"string","minLength":1,"maxLength":20},"attributes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","additionalProperties":{}}},"description":"Attributes in Amazon listing format, each one an array of entries. For an offer: condition, price, quantity or fulfillment channel, for example `condition_type: [{ value: \"new_new\" }]`, `purchasable_offer: [{ currency: \"EUR\", our_price: [{ schedule: [{ value_with_tax: 19.99 }] }] }]` and `fulfillment_availability: [{ fulfillment_channel_code: \"DEFAULT\", quantity: 10 }]`; `merchant_suggested_asin` is filled from `asin`. For a new product, the whole listing. A parent of a variation family: `parentage_level: [{ value: \"parent\" }]`, `child_parent_sku_relationship: [{}]`, `variation_theme: [{ name }]` and the product facts, with no offer and no EAN. A child: `parentage_level: [{ value: \"child\" }]`, `child_parent_sku_relationship: [{ parent_sku }]`, the same `variation_theme` and its attributes, plus the brand, the EAN (`externally_assigned_product_identifier`) or the GTIN exemption, images and the offer."}},"required":["connection","marketplace","sku","attributes"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending"]},"warnings":{"type":"array","items":{"type":"string","enum":["out_of_whitelist","asin_listed_under_another_sku"]},"description":"`out_of_whitelist`: the product whitelist of the connection leaves this SKU out, so it will not show in Epinium until someone adds it there. `asin_listed_under_another_sku` (vendor): that vendor code already lists this ASIN under another SKU; tell the user."}},"required":["id","status","warnings"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pending-listing-changes":{"get":{"summary":"List the listing changes saved in Epinium and pending to publish to Amazon","tags":["pending-listing-changes"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"connection","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"marketplace","in":"query","description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`).","schema":{"type":"string","minLength":2,"maxLength":40}},{"name":"search","in":"query","description":"Case-insensitive substring match over the SKU, the ASIN, the previous value and the new value of the change. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sku":{"nullable":true,"type":"string"},"asin":{"nullable":true,"type":"string"},"connection":{"type":"string"},"marketplace_id":{"nullable":true,"description":"Amazon marketplace id of the product, for example `A1RKKUPIHCS9HS`.","type":"string"},"attribute":{"nullable":true,"description":"The attribute changed, as Epinium stores it.","type":"string"},"previous_value":{"description":"Value before the change."},"new_value":{"description":"Value that will be published."},"changed_by":{"nullable":true,"description":"Name of the user who made the change.","type":"string"},"changed_at":{"type":"string","description":"ISO 8601 date of the change."},"publish_errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"attribute_names":{"type":"array","items":{"type":"string"}}},"required":["code","message","attribute_names"],"additionalProperties":false},"description":"Why Amazon rejected the last attempt to publish this change. Empty when it never failed."}},"required":["id","sku","asin","connection","marketplace_id","attribute","previous_value","new_value","changed_by","changed_at","publish_errors"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"as_of":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"Server time (ISO 8601, UTC) taken before reading this page. When publishing, send the `as_of` of the first page you showed the person as `listed_at`: anything edited or created after it is refused with 409 `selection_changed`."}},"required":["object","data","has_more","as_of"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/pending-listing-changes/publish":{"post":{"summary":"Publish to Amazon a selection of the pending listing changes and new listings","tags":["pending-listing-changes"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"description":"Ids of pending changes, as epinium_list_pending_listing_changes returned them.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"draft_ids":{"description":"Ids of pending new listings, as epinium_list_listing_drafts returned them. A variation family goes together: the parent and its children.","type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}},"all_pending":{"description":"Every pending CHANGE of one connection and marketplace, instead of `ids`. It never includes new listings: those go in `draft_ids`.","type":"object","properties":{"connection":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"marketplace":{"type":"string","minLength":2,"maxLength":40,"description":"Amazon marketplace: its domain (`amazon.es`) or its marketplace id (`A1RKKUPIHCS9HS`)."}},"required":["connection","marketplace"],"additionalProperties":false},"expected_count":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991,"description":"How many changes plus new listings the person saw and approved. If the selection is not exactly that now, nothing is published and the answer is 409 `selection_changed`."},"listed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"The `as_of` of the first page of epinium_list_pending_listing_changes or epinium_list_listing_drafts shown to the person; if both were shown, the older one. A change or new listing edited or created after it gives 409 `selection_changed` and nothing is published."}},"required":["expected_count","listed_at"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"publication_id":{"nullable":true,"description":"The publication, to follow it with `GET /v1/publications/{id}`. `null` when nothing was sent to Amazon (`changes` and `drafts` are 0): there is no publication to follow, and the issue of each new listing is in the pending listings.","type":"string"},"changes":{"type":"number","description":"Pending changes that went into this publication."},"drafts":{"type":"number","description":"New listings that went into this publication. Fewer than `drafts_requested` means some stayed pending, for example a child whose parent is not on Amazon nor in this publication: their issues are in the pending listings."},"drafts_requested":{"type":"number","description":"New listings sent in `draft_ids`."}},"required":["publication_id","changes","drafts","drafts_requested"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/publications":{"get":{"summary":"List the publications to Amazon, newest first","tags":["publications"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"in_flight","in":"query","description":"`true` lists only the publications still in progress; `false` only the finished ones.","schema":{"type":"string","enum":["true","false"]}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The upload request id."},"requested_at":{"type":"string","description":"ISO 8601 date of the Publish click."},"user_name":{"type":"string"},"in_flight":{"type":"boolean","description":"`true` while any visible country is not finished: keep asking until it is `false`."},"status":{"type":"string","enum":["queued","processing","importing","done","done_with_errors"],"description":"`importing`: Amazon already answered everything and accepted new listings are still being brought into Epinium."},"total":{"type":"number"},"accepted":{"type":"number"},"rejected":{"type":"number"},"pending":{"type":"number"},"waiting_parent":{"type":"number"},"with_warnings":{"type":"number"},"countries":{"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string"},"connection_name":{"nullable":true,"type":"string"},"country_code":{"nullable":true,"type":"string"},"transport":{"nullable":true,"type":"string","enum":["feed","patch","put"]},"status":{"type":"string","enum":["queued","processing","importing","done","done_with_errors"],"description":"`importing`: Amazon already answered everything and accepted new listings are still being brought into Epinium."},"total":{"type":"number"},"accepted":{"type":"number"},"rejected":{"type":"number"},"pending":{"type":"number"},"waiting_parent":{"type":"number","description":"Variation children waiting for Amazon to create their parent; counted in `pending`."},"importing":{"type":"number","description":"New listings accepted by Amazon and not yet in Epinium; counted in `accepted`."},"imported":{"type":"number","description":"New listings accepted by Amazon and already in Epinium; counted in `accepted`."},"not_found":{"type":"number","description":"Accepted new listings that never showed up in Epinium after the retries, or that the country closed without."},"closed_reason":{"nullable":true,"description":"Set when Epinium closed the country without an answer from Amazon.","type":"string","enum":["no_response"]}},"required":["connection_id","connection_name","country_code","transport","status","total","accepted","rejected","pending","waiting_parent","importing","imported","not_found","closed_reason"],"additionalProperties":false}},"rejections":{"type":"array","items":{"type":"object","properties":{"product_id":{"nullable":true,"type":"string"},"sku":{"type":"string"},"country_code":{"nullable":true,"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"attribute_names":{"type":"array","items":{"type":"string"}}},"required":["severity","code","message","attribute_names"],"additionalProperties":false}}},"required":["product_id","sku","country_code","issues"],"additionalProperties":false}},"rejections_truncated":{"type":"boolean"},"pending_imports":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"country_code":{"nullable":true,"type":"string"},"accepted_at":{"nullable":true,"type":"string"},"not_found":{"type":"boolean"}},"required":["sku","country_code","accepted_at","not_found"],"additionalProperties":false}},"pending_imports_truncated":{"type":"boolean"}},"required":["id","requested_at","user_name","in_flight","status","total","accepted","rejected","pending","waiting_parent","with_warnings","countries","rejections","rejections_truncated","pending_imports","pending_imports_truncated"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/publications/{id}":{"get":{"summary":"Retrieve one publication and how it is going","tags":["publications"],"parameters":[{"name":"id","in":"path","description":"The publication id, which is its upload request id.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The upload request id."},"requested_at":{"type":"string","description":"ISO 8601 date of the Publish click."},"user_name":{"type":"string"},"in_flight":{"type":"boolean","description":"`true` while any visible country is not finished: keep asking until it is `false`."},"status":{"type":"string","enum":["queued","processing","importing","done","done_with_errors"],"description":"`importing`: Amazon already answered everything and accepted new listings are still being brought into Epinium."},"total":{"type":"number"},"accepted":{"type":"number"},"rejected":{"type":"number"},"pending":{"type":"number"},"waiting_parent":{"type":"number"},"with_warnings":{"type":"number"},"countries":{"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string"},"connection_name":{"nullable":true,"type":"string"},"country_code":{"nullable":true,"type":"string"},"transport":{"nullable":true,"type":"string","enum":["feed","patch","put"]},"status":{"type":"string","enum":["queued","processing","importing","done","done_with_errors"],"description":"`importing`: Amazon already answered everything and accepted new listings are still being brought into Epinium."},"total":{"type":"number"},"accepted":{"type":"number"},"rejected":{"type":"number"},"pending":{"type":"number"},"waiting_parent":{"type":"number","description":"Variation children waiting for Amazon to create their parent; counted in `pending`."},"importing":{"type":"number","description":"New listings accepted by Amazon and not yet in Epinium; counted in `accepted`."},"imported":{"type":"number","description":"New listings accepted by Amazon and already in Epinium; counted in `accepted`."},"not_found":{"type":"number","description":"Accepted new listings that never showed up in Epinium after the retries, or that the country closed without."},"closed_reason":{"nullable":true,"description":"Set when Epinium closed the country without an answer from Amazon.","type":"string","enum":["no_response"]}},"required":["connection_id","connection_name","country_code","transport","status","total","accepted","rejected","pending","waiting_parent","importing","imported","not_found","closed_reason"],"additionalProperties":false}},"rejections":{"type":"array","items":{"type":"object","properties":{"product_id":{"nullable":true,"type":"string"},"sku":{"type":"string"},"country_code":{"nullable":true,"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"attribute_names":{"type":"array","items":{"type":"string"}}},"required":["severity","code","message","attribute_names"],"additionalProperties":false}}},"required":["product_id","sku","country_code","issues"],"additionalProperties":false}},"rejections_truncated":{"type":"boolean"},"pending_imports":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"country_code":{"nullable":true,"type":"string"},"accepted_at":{"nullable":true,"type":"string"},"not_found":{"type":"boolean"}},"required":["sku","country_code","accepted_at","not_found"],"additionalProperties":false}},"pending_imports_truncated":{"type":"boolean"}},"required":["id","requested_at","user_name","in_flight","status","total","accepted","rejected","pending","waiting_parent","with_warnings","countries","rejections","rejections_truncated","pending_imports","pending_imports_truncated"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/listing-drafts/{id}":{"delete":{"summary":"Discard a new offer that was not published yet","tags":["listing-drafts"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["discarded"]}},"required":["id","status"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/prompts":{"get":{"summary":"List the authenticated account's custom prompts","tags":["prompts"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the prompt name. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a custom prompt","tags":["prompts"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":200,"description":"Name shown in Settings > Prompts of the Epinium app. At least 3 characters."},"instruction":{"type":"string","minLength":1,"maxLength":2000,"description":"What the AI must follow when it writes the listing content, in plain language: tone, structure, words to use or avoid. Up to 2000 characters. It is applied when content is generated, never on its own."},"fields":{"description":"Listing fields the prompt applies to: titleAndHighlights (title plus Item Highlights, generated together), product_description, bullet_point or generic_keyword (search terms). Omit it or send [] to use the prompt for every field.","maxItems":4,"type":"array","items":{"type":"string","enum":["titleAndHighlights","product_description","bullet_point","generic_keyword"]}}},"required":["name","instruction"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/prompts/{id}":{"get":{"tags":["prompts"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Rename a custom prompt or change its instruction or fields","tags":["prompts"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name.","type":"string","minLength":3,"maxLength":200},"instruction":{"description":"New instruction, replacing the current one. Up to 2000 characters.","type":"string","minLength":1,"maxLength":2000},"fields":{"description":"New list of listing fields, replacing the current one. Send [] to use the prompt for every field.","maxItems":4,"type":"array","items":{"type":"string","enum":["titleAndHighlights","product_description","bullet_point","generic_keyword"]}}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"instruction":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Listing fields the prompt applies to: titleAndHighlights, product_description, bullet_point, generic_keyword. Empty means every field. An older prompt can still carry the deprecated item_name (the title alone, replaced by titleAndHighlights)."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","instruction","fields","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/advertising-changes":{"get":{"summary":"List the changes Epinium pushed to Amazon for the authenticated account","tags":["advertising-changes"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"campaign","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"adgroup","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"entity","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"entity_type","in":"query","schema":{"type":"string","enum":["campaign","adgroup","target","productAd","portfolio"]}},{"name":"source","in":"query","schema":{"type":"string","enum":["front","workflow","public-api","mcp","system"]}},{"name":"result","in":"query","schema":{"type":"string","enum":["applied","failed"]}},{"name":"field","in":"query","schema":{"type":"string"}},{"name":"correlation_id","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"entity_type":{"type":"string","enum":["campaign","adgroup","target","productAd","portfolio"]},"entity_id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"adgroup":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"field":{"type":"string"},"old_value":{},"new_value":{},"source":{"type":"string","enum":["front","workflow","public-api","mcp","system"]},"actor":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","apiKey","oauthClient","system"]},"id":{"type":"string"},"label":{"type":"string"}},"required":["type"],"additionalProperties":false},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"},"profile_id":{"nullable":true,"type":"string"},"ad_product":{"nullable":true,"type":"string","enum":["SPONSORED_PRODUCTS","SPONSORED_BRANDS","SPONSORED_DISPLAY"]},"correlation_id":{"nullable":true,"type":"string"}},"required":["id","at","entity_type","entity_id","campaign","adgroup","field","source","actor","result","error","profile_id","ad_product","correlation_id"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks":{"get":{"summary":"List the authenticated account's tasks","tags":["tasks"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the task title. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","resolved","discarded"]}},{"name":"priority","in":"query","schema":{"type":"string","enum":["high","medium","low"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a task with its suggestions","tags":["tasks"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"priority":{"type":"string","enum":["high","medium","low"]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"items":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"entityModel":{"type":"string","enum":["products","campaigns","adgroups","targets","search_terms","product_ads"]},"displayName":{"type":"string","maxLength":200},"displayId":{"type":"string","maxLength":100},"problemLabel":{"type":"string","maxLength":200},"problemSeverity":{"type":"string","enum":["error","warning","info"]},"fieldName":{"type":"string","maxLength":100},"fieldPath":{"type":"string","maxLength":300},"valueType":{"type":"string","enum":["string","text","number","boolean","string_array","html"]},"currentValue":{},"suggestedValue":{}},"required":["entityId","entityModel"],"additionalProperties":false}}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks/{id}":{"get":{"tags":["tasks"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Change a task's metadata","tags":["tasks"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"priority":{"type":"string","enum":["high","medium","low"]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks/{id}/resolve":{"post":{"summary":"Resolve or discard a task","tags":["tasks"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks/{id}/apply":{"post":{"summary":"Apply a task's approved suggestions","tags":["tasks"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."}}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"enqueued":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bulk":{"nullable":true,"type":"string"}},"required":["applied","failed","enqueued","skipped","bulk"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/tasks/listing-optimizations":{"post":{"summary":"Rewrite listings with Epinium's AI into suggestions of a task","tags":["tasks"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"description":"Catalog product ids (Amazon seller or vendor products of this account) to rewrite."},"fields":{"description":"Fields to rewrite. `title` also writes the Item Highlights. Default: all four.","minItems":1,"type":"array","items":{"type":"string","enum":["title","bullets","description","search_terms"]}},"title":{"description":"Title of the task, in the person's language, used only if the task does not exist yet.","type":"string","minLength":1,"maxLength":200}},"required":["products"],"additionalProperties":false}}}},"responses":{"202":{"description":"202","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["listing_optimization"]},"task":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"products":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fields":{"type":"array","items":{"type":"string","enum":["title","bullets","description","search_terms"]}},"limit":{"type":"object","properties":{"cap":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["cap","used","remaining"],"additionalProperties":false}},"required":["object","task","products","fields","limit"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/task-items":{"get":{"summary":"List the authenticated account's task items","tags":["task-items"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the item display name, display id and problem label. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"task","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"entityModel","in":"query","schema":{"type":"string","enum":["products","campaigns","adgroups","targets","search_terms","product_ads"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"task":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}]},"entityId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"entityModel":{"type":"string","enum":["products","campaigns","adgroups","targets","search_terms","product_ads"]},"displayName":{"nullable":true,"type":"string"},"displayId":{"nullable":true,"type":"string"},"problemLabel":{"nullable":true,"type":"string"},"problemSeverity":{"nullable":true,"type":"string","enum":["error","warning","info"]},"fieldName":{"nullable":true,"type":"string"},"fieldPath":{"nullable":true,"type":"string"},"valueType":{"nullable":true,"type":"string","enum":["string","text","number","boolean","string_array","html"]},"currentValue":{},"suggestedValue":{},"appliedValue":{},"status":{"type":"string","enum":["pending","approved","rejected"]},"autoApplySkipped":{"nullable":true,"type":"boolean"},"applyError":{"nullable":true,"type":"string"},"appliedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","task","entityId","entityModel","displayName","displayId","problemLabel","problemSeverity","fieldName","fieldPath","valueType","currentValue","suggestedValue","appliedValue","status","autoApplySkipped","applyError","appliedAt","resolvedAt","createdAt","updatedAt"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/task-items/{id}":{"get":{"tags":["task-items"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"expand","in":"query","description":"Inline related records instead of returning just their ids. Repeat the param for several (`expand[]=connection&expand[]=country`) and nest with dot notation (`connection.country`), up to 4 levels. Each expanded record is charged like a row of its own resource, once per row that carries it (most cost 1 credit, countries are free): expanding two relations on 100 rows adds about 200 credits, so expand only what the answer needs.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"task":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"title":{"type":"string"},"description":{"nullable":true,"type":"string"},"status":{"type":"string","enum":["pending","resolved","discarded"]},"priority":{"nullable":true,"type":"string","enum":["high","medium","low"]},"origin":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["user","chat","workflow","system","api"]},"sourceName":{"nullable":true,"type":"string"}},"required":["type","sourceName"],"additionalProperties":false},"entityCounts":{"type":"object","additionalProperties":{"type":"number"}},"itemCount":{"type":"number"},"pendingItemCount":{"type":"number"},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolution":{"nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["resolved","discarded"]},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["action","resolvedAt"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","title","description","status","priority","origin","entityCounts","itemCount","pendingItemCount","expiresAt","resolution","createdAt","updatedAt"],"additionalProperties":false}]},"entityId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"entityModel":{"type":"string","enum":["products","campaigns","adgroups","targets","search_terms","product_ads"]},"displayName":{"nullable":true,"type":"string"},"displayId":{"nullable":true,"type":"string"},"problemLabel":{"nullable":true,"type":"string"},"problemSeverity":{"nullable":true,"type":"string","enum":["error","warning","info"]},"fieldName":{"nullable":true,"type":"string"},"fieldPath":{"nullable":true,"type":"string"},"valueType":{"nullable":true,"type":"string","enum":["string","text","number","boolean","string_array","html"]},"currentValue":{},"suggestedValue":{},"appliedValue":{},"status":{"type":"string","enum":["pending","approved","rejected"]},"autoApplySkipped":{"nullable":true,"type":"boolean"},"applyError":{"nullable":true,"type":"string"},"appliedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"resolvedAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","task","entityId","entityModel","displayName","displayId","problemLabel","problemSeverity","fieldName","fieldPath","valueType","currentValue","suggestedValue","appliedValue","status","autoApplySkipped","applyError","appliedAt","resolvedAt","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Approve or reject one suggestion","tags":["task-items"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["approved","rejected"]},"appliedValue":{}},"required":["status"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"},"autoApplySkipped":{"type":"boolean"}},"required":["id","result","error","autoApplySkipped"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/task-items/batch":{"post":{"summary":"Approve or reject many suggestions at once","tags":["task-items"],"parameters":[{"name":"idempotency-key","in":"header","description":"Any string identifying this intent, up to 255 characters. Reuse the same value when retrying the same change: without it a network timeout turns one write into two.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"status":{"type":"string","enum":["approved","rejected"]},"appliedValue":{}},"required":["id","status"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"result":{"type":"string","enum":["applied","failed"]},"error":{"nullable":true,"type":"string"},"autoApplySkipped":{"type":"boolean"}},"required":["id","result","error","autoApplySkipped"],"additionalProperties":false}},"applied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","data","applied","failed"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows":{"get":{"description":"Filter by `description_key` to tell workflow types apart: `name` and `name_key` are NOT reliable discriminators because several templates share a display name. `template` filters by the global template a workflow was cloned from. Global templates themselves are never listed here — only the account's own workflows.","summary":"List the authenticated account's workflows","tags":["workflows"],"parameters":[{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true},{"name":"search","in":"query","description":"Case-insensitive substring match over the workflow name and description. Use it to find a record by name when you do not have its id, instead of paging through the whole list. Regex metacharacters are matched literally.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include_total","in":"query","description":"Set to `true` to also receive `total_count`: how many records match every filter of this request, ignoring `starting_after`/`ending_before`/`offset` - the size of the whole result set, not of what is left. `has_more` is always returned regardless. It costs an extra count query, so ask for it once, on the first page, to decide whether the set is worth walking. On metrics resources it counts entities (or groups with `group_by`), and, with any `granularity` other than `total`, each of their periods that has data, not entities times periods: entity-days with `granularity=daily`. `total_count` comes back `null` when the count could not finish in time; the list is still returned, so treat it as unknown, never as zero.","schema":{"type":"string","enum":["true","false"]}},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"template","in":"query","description":"24-character hexadecimal Mongo ObjectId.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"description_key","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"description":"The workflow is created PAUSED, so it does nothing until a human turns it on in the app — this endpoint cannot activate it, with or without a `schedule`. Sending `schedule` only says WHEN it would run once somebody enables it; it never makes it run. The graph must pass validation: on failure you get 422 with the same error list `validate` returns, and nothing is written. Requires the `workflows:write` scope.","summary":"Create a workflow, paused","tags":["workflows"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"nodes":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"source":{"type":"string","minLength":1},"target":{"type":"string","minLength":1},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target"],"additionalProperties":false}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"type":{"type":"string","enum":["number","boolean","string","select","multiselect","string-list"]},"value":{},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"nullable":true,"type":"boolean"}},"required":["key","type","value"]}},"schedule":{"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"nullable":true,"type":"string"}},"required":["type"]}},"required":["name","nodes","edges"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"422","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"node_id":{"nullable":true,"type":"string"},"edge_id":{"nullable":true,"type":"string"}},"required":["code","message","hint","node_id","edge_id"],"additionalProperties":false}},"guidance":{"type":"string"}},"required":["valid","errors"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}":{"get":{"description":"Returns the full definition: the node graph, and every configuration variable with its effective value. `overridden` on a variable tells you whether the customer set it or it still carries the template default — which is usually the question worth asking when auditing a setup.","summary":"Retrieve one workflow with its resolved configuration","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"fields","in":"query","description":"Trim the response to the fields you need, comma-separated and keyed by ENTITY TYPE rather than by resource name: `fields[campaign]=id,name`. An unknown key or field name is rejected with a 400 that lists the valid ones.","schema":{"type":"object","additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"description":"Deletes the workflow, its execution history, the payloads of those executions and its version snapshots. There is no undo and no bin: once gone, the record of what it did is gone with it. Requires the `workflows:write` scope.","summary":"Delete a workflow and everything under it","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"204":{"description":"204","content":{"application/json":{"schema":{}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"description":"Editing the graph only works while the workflow is paused: doing it on one that is scheduled returns 409, and so does sending `schedule` for a workflow that is active at all. The one exception is `active: false` on its own, which is ALWAYS allowed — pausing can only make less happen on Amazon, and refusing it would leave a scheduled workflow impossible to edit through this API at all. Sending `active: true` turns the workflow on: from then on its schedule fires for real — because its next run moves real bids and a half-reviewed graph should not be what executes. Pause it in the app first. `nodes` and `edges` are replaced wholesale and must be sent together — a partial patch would leave edges pointing at nodes that no longer exist, so sending one without the other is a 400, as is an empty body. The graph must pass validation: on failure you get 422 and nothing is written. Requires the `workflows:write` scope.","summary":"Edit a paused workflow, or pause one","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"nodes":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"source":{"type":"string","minLength":1},"target":{"type":"string","minLength":1},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target"],"additionalProperties":false}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"type":{"type":"string","enum":["number","boolean","string","select","multiselect","string-list"]},"value":{},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"nullable":true,"type":"boolean"}},"required":["key","type","value"]}},"schedule":{"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"nullable":true,"type":"string"}},"required":["type"]},"active":{"type":"boolean"},"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"422","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"node_id":{"nullable":true,"type":"string"},"edge_id":{"nullable":true,"type":"string"}},"required":["code","message","hint","node_id","edge_id"],"additionalProperties":false}},"guidance":{"type":"string"}},"required":["valid","errors"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/campaigns":{"get":{"description":"NOT simply the campaigns that link to the workflow. Membership is decided by three controls stored per campaign (force-include, force-exclude, global opt-out) combined with the workflow's own filter and its auto-selection setting. Each row carries a `gate` object saying why it is in, plus the campaign's effective AI configuration. When the set is empty, `empty_reason` names the cause: `manual-sin-enlaces` means the workflow is on manual selection with nothing linked — the state a workflow is BORN in, and the usual reason one runs nightly for weeks doing nothing. `filtro-vacio` means no campaign passes its own filter. `no-itera-campanas` means this workflow does not act on campaigns at all.","summary":"Campaigns this workflow actually processes","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"campaign_id":{"type":"string"},"name":{"type":"string"},"state":{"nullable":true,"type":"string"},"ad_product":{"nullable":true,"type":"string"},"config":{"type":"object","properties":{"objective_type":{"nullable":true,"type":"string"},"objective_value":{"nullable":true,"type":"number"},"min_bid":{"nullable":true,"type":"number"},"max_bid":{"nullable":true,"type":"number"},"placement_cap_percent":{"nullable":true,"type":"number"},"daily_budget":{"nullable":true,"type":"number"},"monthly_budget":{"nullable":true,"type":"number"},"ai_enabled":{"type":"boolean"},"optimizing_since":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["objective_type","objective_value","min_bid","max_bid","placement_cap_percent","daily_budget","monthly_budget","ai_enabled","optimizing_since"],"additionalProperties":false},"gate":{"type":"object","properties":{"linked":{"type":"boolean"},"excluded":{"type":"boolean"},"opt_out":{"type":"boolean"},"matched_own_filter":{"type":"boolean"}},"required":["linked","excluded","opt_out","matched_own_filter"],"additionalProperties":false}},"required":["id","campaign_id","name","state","ad_product","config","gate"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"},"empty_reason":{"nullable":true,"type":"string","enum":["manual-sin-enlaces","filtro-vacio","no-itera-campanas"]}},"required":["object","data","has_more","empty_reason"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/performance":{"get":{"description":"Aggregated over a required `start_date`/`end_date` window, restricted to the campaigns the workflow actually processes. Each row puts the configured `objective_type`/`objective_value` next to the realized metrics, which is how you judge whether the workflow is hitting its target. `optimizing_since` is when the workflow first touched that campaign for real — results before that date are NOT its doing, so a window straddling it will mislead you. Monetary amounts are decimal strings; ratios are fractions (0.1642 = 16.42%) and are `null`, never `0`, when their denominator is zero.","summary":"Advertising performance of the campaigns this workflow optimizes","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"start_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-01"}},{"name":"end_date","in":"query","description":"Both ends are included in the range. The window is capped, and the cap depends on the resource AND on `granularity` — `daily` allows a much shorter span than `total`, and `target-metrics` and `search-term-metrics` are stricter than the rest because `limit`/`offset` bound the response but not what ClickHouse scans. Going over returns a `400` naming the exact limit for your request.","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"}},{"name":"granularity","in":"query","description":"`total` (default) aggregates the whole window into one row per campaign, which is the row to compare against its objective. `daily` splits each campaign into one row per day with activity, but these rows carry no `date` field, so they cannot be told apart: for a dated daily series use `campaign-metrics` with `campaign` and `granularity=daily`. Calendar periods (`weekly`, `monthly`, `quarterly`, `yearly`) are not available on this route. `daily` has a shorter window cap than `total`.","schema":{"default":"total","example":"total","type":"string","enum":["total","daily"]}},{"name":"limit","in":"query","description":"Page size. For a top-N, combine `order_by` with a small `limit` instead of raising it: `limit`/`offset` bound the response, not what ClickHouse scans.","schema":{"default":100,"example":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","schema":{"default":0,"example":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"order","in":"query","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"campaign":{"type":"string"},"campaign_name":{"nullable":true,"type":"string"},"currency":{"type":"string"},"cost":{"type":"string"},"sales":{"type":"string","description":"Total attributed sales, the same figure as sales in campaign metrics. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"impressions":{"type":"number"},"clicks":{"type":"number"},"orders":{"type":"number","description":"Total attributed orders, the same figure as orders in campaign metrics. Attribution window, the same as the Amazon Ads console: Sponsored Products uses 7 days on seller accounts and 14 days on vendor accounts; Sponsored Brands and Sponsored Display only have the 14-day window."},"acos":{"nullable":true,"type":"number"},"roas":{"nullable":true,"type":"number"},"ctr":{"nullable":true,"type":"number"},"conversion_rate":{"nullable":true,"type":"number"},"objective_type":{"nullable":true,"type":"string"},"objective_value":{"nullable":true,"type":"number"},"optimizing_since":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["campaign","campaign_name","currency","cost","sales","impressions","clicks","orders","acos","roas","ctr","conversion_rate","objective_type","objective_value","optimizing_since"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/executions":{"get":{"description":"What the workflow has actually done, run by run. `status` tells them apart, and `partial` is its own outcome, not a shade of the other two: the graph finished but some items inside a forEach failed and the rest carried on, so neither \"it all worked\" nor \"nothing happened\" is true. `dry_run` says whether the run wrote anything at all — filter it out before drawing conclusions from a series. The per-node detail of a run is in its payloads.","summary":"Runs of a workflow, newest first","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"dry_run","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"workflow":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"status":{"type":"string","enum":["pending","running","completed","partial","failed","cancelled"]},"dry_run":{"type":"boolean"},"error":{"nullable":true,"type":"string"},"tokens_consumed":{"type":"number"},"node_result_count":{"type":"number"},"started_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"completed_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","workflow","status","dry_run","error","tokens_consumed","node_result_count","started_at","completed_at","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/executions/{executionId}/payloads":{"get":{"description":"The output every node left behind in that run — this is where a workflow's decisions actually are, one row per node and per forEach item. Read this, not the run itself, to answer what a workflow decided and why: the run document only carries the top-level nodes, and in this product the reasoning lives inside the forEach.\n\nIt takes two calls, on purpose. The first, with the default `data=none`, is the INDEX: every step with its `label`, and nothing else. A `label` starts with the CONTAINER — the forEach the work happened in — then the item, then the node that did it: `wf-foreach-targets-item-2-p9747-wf-calc-bid`. So `label_prefix` takes the container, not the node at the end. Read the index first and copy a prefix from it rather than composing one; a prefix that matches nothing is rejected and the error lists the ones that exist. Asking for `data=full` across a whole run of a catalogue-sized workflow returns millions of characters and overflows what a host will accept, which is why it is not the default. `type` separates a node's own decision (`nodeResult`) from the engine's scaffolding.","summary":"What each node produced in a run","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"executionId","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}},{"name":"label_prefix","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["subGraph","context","nodeResult"]}},{"name":"data","in":"query","schema":{"type":"string","enum":["none","full"]}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"type":{"type":"string","enum":["subGraph","context","nodeResult"]},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}}},"required":["id","type","label"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/executions/{executionId}/summary":{"get":{"description":"The whole of a run in one answer: per campaign, how many bids it raised, lowered or kept, how many search terms it harvested, negated, isolated or left waiting, and how many budgets it moved. Use it to tell the person what a simulation would do across EVERY campaign before turning the workflow on. Each campaign also carries up to two `examples`, decisions of different kinds with changes first: the keyword, ASIN, category or search term (`entity.text`), the `decision`, its `reason` (the key of the rule that fired, such as `sales_high_acos_lower` or `productive_term`, to be explained with `metrics`: clicks, sales, and ACOS against the target as decimals) and `previous_value`/`new_value` (the bid of a target, the suggested bid of the keyword a harvested term would create, the daily budget of a campaign). The payloads are only for going deeper into one decision. These are the optimizer's own decisions, with the campaign and workflow bid ceilings already applied; Amazon's recommended-bid range is applied after them and can still cap a raise, or lift an automatic campaign's bid to the start of the range, so present the counts and the bid amounts as approximate, not as exact bids on Amazon. In a simulation (`execution.dry_run: true`) nothing was written. `finished: false` means the run is still going and the counts are partial. `decision_count: 0` on a finished run means this workflow records no optimizer decisions (it is not the bid optimizer) or it processed no campaign. Counts come from the optimizer's decision log, which keeps 90 days.","summary":"What a run decided, counted per campaign","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"executionId","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["workflow_execution_summary"]},"execution":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"workflow":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"status":{"type":"string","enum":["pending","running","completed","partial","failed","cancelled"]},"dry_run":{"type":"boolean"},"error":{"nullable":true,"type":"string"},"tokens_consumed":{"type":"number"},"node_result_count":{"type":"number"},"started_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"completed_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","workflow","status","dry_run","error","tokens_consumed","node_result_count","started_at","completed_at","created_at"],"additionalProperties":false},"finished":{"type":"boolean"},"decision_count":{"type":"number"},"totals":{"type":"object","properties":{"bids":{"type":"object","properties":{"raise":{"type":"number"},"lower":{"type":"number"},"hold":{"type":"number"}},"required":["raise","lower","hold"],"additionalProperties":false},"search_terms":{"type":"object","properties":{"harvest":{"type":"number"},"negative":{"type":"number"},"isolate":{"type":"number"},"wait":{"type":"number"}},"required":["harvest","negative","isolate","wait"],"additionalProperties":false},"budgets":{"type":"object","properties":{"raise":{"type":"number"},"lower":{"type":"number"},"hold":{"type":"number"}},"required":["raise","lower","hold"],"additionalProperties":false}},"required":["bids","search_terms","budgets"],"additionalProperties":false},"campaigns":{"type":"array","items":{"type":"object","properties":{"bids":{"type":"object","properties":{"raise":{"type":"number"},"lower":{"type":"number"},"hold":{"type":"number"}},"required":["raise","lower","hold"],"additionalProperties":false},"search_terms":{"type":"object","properties":{"harvest":{"type":"number"},"negative":{"type":"number"},"isolate":{"type":"number"},"wait":{"type":"number"}},"required":["harvest","negative","isolate","wait"],"additionalProperties":false},"budgets":{"type":"object","properties":{"raise":{"type":"number"},"lower":{"type":"number"},"hold":{"type":"number"}},"required":["raise","lower","hold"],"additionalProperties":false},"campaign":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"nullable":true,"type":"string"},"examples":{"type":"array","items":{"type":"object","properties":{"decision":{"type":"string"},"entity":{"type":"object","properties":{"type":{"type":"string","enum":["keyword","asin","brand","category","auto","target","search_term","campaign"]},"id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"text":{"nullable":true,"type":"string"},"match_type":{"nullable":true,"type":"string"}},"required":["type","id","text","match_type"],"additionalProperties":false},"reason":{"nullable":true,"type":"string"},"detail":{"nullable":true,"type":"string"},"previous_value":{"nullable":true,"type":"number"},"new_value":{"nullable":true,"type":"number"},"metrics":{"nullable":true,"type":"object","properties":{"clicks":{"nullable":true,"type":"number"},"sales":{"nullable":true,"type":"number"},"acos":{"nullable":true,"type":"number"},"target_acos":{"nullable":true,"type":"number"}},"required":["clicks","sales","acos","target_acos"],"additionalProperties":false}},"required":["decision","entity","reason","detail","previous_value","new_value","metrics"],"additionalProperties":false}}},"required":["bids","search_terms","budgets","campaign","name","examples"],"additionalProperties":false}},"campaign_count":{"type":"number"},"other_decisions":{"type":"object","additionalProperties":{"type":"number"}}},"required":["object","execution","finished","decision_count","totals","campaigns","campaign_count","other_decisions"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflow-node-types":{"get":{"description":"Everything the workflow engine understands: the node types and what each is for, which fields their `data` needs and which the server fills in for you, the actions a node can run, the operators a condition accepts, and what a forEach can iterate over. Read it BEFORE building a graph - without it the only way to learn the shape is to read an existing workflow and infer, and an account with no workflow of the kind you need leaves you guessing. Identical for every account, so it is not charged.","summary":"What a workflow graph can be made of","tags":["workflows"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"node_types":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"purpose":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"filled_by_server":{"type":"boolean"},"default_value":{},"required":{"type":"boolean"},"description":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","object","array"]},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["name","type","required","description"],"additionalProperties":false}}},"required":["name","filled_by_server","default_value"],"additionalProperties":false}},"source_handles":{"type":"array","items":{"type":"string"}}},"required":["type","purpose","fields","source_handles"],"additionalProperties":false}},"action_types":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"group":{"type":"string","enum":["general","campaign-optimizer"]},"config_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","object","array"]},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["name","type","required","description"],"additionalProperties":false}}},"required":["action","group"],"additionalProperties":false}},"config_envelope":{"type":"string"},"condition_operators":{"type":"array","items":{"type":"string"}},"condition_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","object","array"]},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["name","type","required","description"],"additionalProperties":false}},"for_each":{"type":"object","properties":{"modes":{"type":"array","items":{"type":"string"}},"collections":{"type":"array","items":{"type":"string"}}},"required":["modes","collections"],"additionalProperties":false}},"required":["node_types","action_types","config_envelope","condition_operators","condition_fields","for_each"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/versions":{"get":{"description":"Every create, clone, instantiation and edit leaves a version behind, and so does a restore — restoring is never a one-way trip. Versions EXPIRE, so an old workflow can show fewer than were actually made: a short list does not mean nobody touched it. `author` says where the change came from, which is what separates an edit made by an integration from one made by hand in Epinium. The graph is not here; read one version to see it.","summary":"Saved versions of a workflow, newest first","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"limit","in":"query","description":"Page size. The default is enough to explore; raise it only when you need to walk a whole collection.","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for the next page: the `id` of the last record you received. Returns the records after it.","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor for the previous page: the `id` of the first record you received. Returns the records before it.","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"workflow":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean"},"node_count":{"type":"number"},"author":{"nullable":true,"type":"object","properties":{"source":{"type":"string","enum":["app","public-api","mcp","chat"]},"credential_type":{"nullable":true,"type":"string","enum":["api_key","oauth"]}},"required":["source","credential_type"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","workflow","name","description","active","node_count","author","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/versions/{versionId}":{"get":{"description":"The full graph as it was when that version was saved. Read it before restoring: restoring replaces the live graph wholesale, and this is the only way to see what it would become.","summary":"One saved version, with its graph","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"versionId","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"workflow":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean"},"node_count":{"type":"number"},"author":{"nullable":true,"type":"object","properties":{"source":{"type":"string","enum":["app","public-api","mcp","chat"]},"credential_type":{"nullable":true,"type":"string","enum":["api_key","oauth"]}},"required":["source","credential_type"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}}},"required":["id","workflow","name","description","active","node_count","author","created_at","nodes","edges","variables"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/versions/{versionId}/restore":{"post":{"description":"Replaces the live graph with the one from that version. It is an edit, so the same rule applies: a workflow that can fire on its own is refused with 409 — pause it first with `active: false`, restore, and turn it back on when the result is what you wanted. The state being replaced is snapshotted first, so a restore can itself be undone. Requires the `workflows:write` scope.","summary":"Put a saved version back","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"versionId","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/cost-estimate":{"get":{"description":"The same forecast the app shows in the workflow detail, so read it BEFORE `run` with `dry_run: false` on anything that touches a large catalogue. A row closes exactly: `estimated_items * tokens_per_item + loop_tokens = estimated_tokens`. Do NOT multiply by `billable_nodes_per_item` — it counts the nodes rather than pricing them, and a `create-task` does not cost the same as a plain action. What the number is worth depends on one flag. For the rows with `forecastable: true` it is an UPPER bound: it counts every item that matches today, and a run can process fewer. But a row with `forecastable: false` is a `forEach` whose size cannot be known until the run happens, and its cost is left OUT of the total — so if any row carries that flag the total is not an upper bound at all, it is incomplete, and the real cost can exceed it. A zero there means 'not forecast', never 'free'.","summary":"What running this workflow would cost, without running it","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"estimated_tokens":{"type":"number"},"breakdown":{"type":"array","items":{"type":"object","properties":{"node":{"type":"string"},"node_type":{"type":"string"},"label":{"type":"string"},"estimated_items":{"type":"number"},"billable_nodes_per_item":{"type":"number"},"tokens_per_item":{"type":"number"},"loop_tokens":{"type":"number"},"estimated_tokens":{"type":"number"},"forecastable":{"type":"boolean"}},"required":["node","node_type","estimated_items","billable_nodes_per_item","tokens_per_item","loop_tokens","estimated_tokens","forecastable"],"additionalProperties":false}}},"required":["estimated_tokens","breakdown"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/run":{"post":{"description":"Queues an execution and returns its id — it does NOT wait for it to finish, because a run over dozens of campaigns takes far longer than any tool call. Read the outcome afterwards with the executions and payloads of this same workflow. `dry_run` is required and has no default on purpose: a real run moves bids and budgets on Amazon, and a simulation walks the whole graph writing nothing, so which one you meant should never depend on a field you forgot. A paused workflow can still be simulated — that is the point, checking it before turning it on — but running it for real needs it active. Requires the `workflows:write` scope.","summary":"Run a workflow now, for real or as a simulation","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"}},"required":["dry_run"],"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"execution":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"status":{"type":"string"},"dry_run":{"type":"boolean"}},"required":["execution","status","dry_run"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/validate":{"post":{"description":"Runs the same structural, connectivity and semantic rules that `create` and `update` enforce, and persists nothing. `name` is optional here, unlike in `create`: nothing is saved, so there is nothing to name. Each error carries a `hint` saying what to change. Use it to iterate on a graph before writing it: a rejected write costs you the same round-trip but leaves you guessing less if you validated first.","summary":"Check a workflow graph without saving it","tags":["workflows"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"nodes":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"source":{"type":"string","minLength":1},"target":{"type":"string","minLength":1},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target"],"additionalProperties":false}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"type":{"type":"string","enum":["number","boolean","string","select","multiselect","string-list"]},"value":{},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"nullable":true,"type":"boolean"}},"required":["key","type","value"]}},"schedule":{"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"nullable":true,"type":"string"}},"required":["type"]}},"required":["nodes","edges"],"additionalProperties":false}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"node_id":{"nullable":true,"type":"string"},"edge_id":{"nullable":true,"type":"string"}},"required":["code","message","hint","node_id","edge_id"],"additionalProperties":false}},"guidance":{"type":"string"}},"required":["valid","errors"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflows/{id}/clone":{"post":{"description":"Copies the graph, the declared variables and the schedule of an existing workflow server-side, so the caller never resends them. Like `create`, the copy is PAUSED and this endpoint cannot turn it on. Use it to run the same logic with different values: `variables` takes only the keys you want to change, and every other one keeps the source value. Requires the `workflows:write` scope.","summary":"Copy an existing workflow, paused","tags":["workflows"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"variables":{"type":"object","additionalProperties":{}}},"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflow-templates":{"get":{"description":"The catalogue of automations Epinium publishes, filtered to the ones this account is allowed to use. These are NOT workflows of the account: they do nothing until you instantiate one, which gives the account its own paused copy. Requires the `workflows:read` scope.","summary":"List the workflow templates this account can instantiate","tags":["workflow-templates"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"node_count":{"type":"number"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","name","description","description_key","node_count","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"total_count":{"description":"Present only when the request had `include_total=true`: absent when it was not requested, `null` when it was requested but the count could not be computed in time, a number - the size of the whole matching set - when it succeeded.","nullable":true,"type":"number"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/workflow-templates/{id}/instantiate":{"post":{"description":"Creates the account's own copy of a template, PAUSED, with the template's graph, variables and schedule already in place — turning it on is a human step in Epinium. Instantiating the same template twice is allowed and gives two independent copies, so check what the account already has first: `epinium_list_workflows` with `template` filters by the template a workflow came from. A template this account is not entitled to returns 403. Requires the `workflows:write` scope.","summary":"Create this account copy of a template","tags":["workflow-templates"],"parameters":[{"name":"id","in":"path","description":"24-character hexadecimal Mongo ObjectId.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"name":{"type":"string"},"name_key":{"nullable":true,"type":"string"},"description":{"type":"string"},"description_key":{"nullable":true,"type":"string"},"template_id":{"nullable":true,"type":"string","pattern":"^[a-f0-9]{24}$","description":"24-character hexadecimal Mongo ObjectId."},"active":{"type":"boolean"},"dry_run":{"type":"boolean"},"customized_by_user":{"type":"boolean"},"schedule":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["cron","interval","once"]},"cron":{"nullable":true,"type":"string"},"interval_ms":{"nullable":true,"type":"number"},"scheduled_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"timezone":{"type":"string"},"enabled":{"type":"boolean"},"last_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"next_run_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["type","cron","interval_ms","scheduled_at","timezone","enabled","last_run_at","next_run_at"],"additionalProperties":false},"node_count":{"type":"number"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"value":{},"overridden":{"type":"boolean"},"description":{"nullable":true,"type":"string"},"group":{"nullable":true,"type":"string"},"options":{"nullable":true,"type":"array","items":{"type":"string"}},"hidden":{"type":"boolean"}},"required":["key","type","value","overridden","description","group","options","hidden"],"additionalProperties":false}},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"nullable":true,"type":"string"},"data":{"type":"object","additionalProperties":{}},"parent_node":{"nullable":true,"type":"string"}},"required":["id","type","label","data","parent_node"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"source_handle":{"nullable":true,"type":"string"},"target_handle":{"nullable":true,"type":"string"}},"required":["id","source","target","source_handle","target_handle"],"additionalProperties":false}}},"required":["id","name","name_key","description","description_key","template_id","active","dry_run","customized_by_user","schedule","node_count","created_at","updated_at","variables","nodes","edges"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"reason":{"type":"string","enum":["trial","whitelist"]}},"required":["type","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/platform-request":{"post":{"operationId":"PlatformRequestController_callPlatform","parameters":[],"responses":{"201":{"description":""}},"tags":["PlatformRequest"]}},"/v1/platform-request/docs/{platform}":{"get":{"operationId":"PlatformRequestController_platformDocs","parameters":[],"responses":{"200":{"description":""}},"tags":["PlatformRequest"]}},"/v1/platform-changes":{"get":{"operationId":"PlatformChangesController_","parameters":[],"responses":{"200":{"description":""}},"tags":["PlatformChanges"]}}},"info":{"title":"Epinium Public API","description":"","version":"1.0.0","contact":{}},"tags":[{"name":"me","description":"Describes the authenticated API key: its scopes and accessible accounts. No scope required — any valid key can call it."},{"name":"onboarding","description":"Skip an onboarding step of the account, or take it up again. No scope required, so a read-only key can store that the person does not want Amazon Ads."},{"name":"accounts","description":"Accounts this API key can operate on, selectable via the `Epinium-Account` header. Requires `connections:read`."},{"name":"connections","description":"The authenticated account's data source connections. Requires `connections:read`."},{"name":"products","description":"The authenticated account's catalog products. Requires `catalog:read`."},{"name":"product-costs","description":"Set a product's unit cost and shipping cost. Requires `costs:write` - a scope of its own, not `catalog:write`, that also writes own expenses (`/v1/expenses`): reading the costs this writes is part of `/v1/pnl/*`, gated by `catalog:read` and plan, not by this one."},{"name":"product-purchases","description":"Purchases from suppliers and the stock groups they belong to: the detailed product cost, where the unit cost is the weighted average of the stock. Reading requires `catalog:read`; recording, correcting and deleting purchases require `costs:write`. Both need a plan that includes product cost (Business or Master). To load many purchases at once, use `POST /v1/cost-imports` with `kind: purchases`."},{"name":"cost-imports","description":"Import the costs of many products at once, from uploaded spreadsheets or from rows, with the same template and rules as the cost import of the Epinium app and a single recalculation of the margin. Requires `costs:write`."},{"name":"amazon-seller-products","description":"The authenticated account's Amazon Seller Central product listings. Requires `catalog:read`."},{"name":"amazon-vendor-products","description":"The authenticated account's Amazon Vendor Central product listings. Requires `catalog:read`."},{"name":"amazon-advertising-products","description":"The authenticated account's Amazon advertising products. Requires `catalog:read`."},{"name":"seller-product-metrics","description":"Seller Central sales and traffic per product, aggregated from the account's report history. Requires `catalog:read`."},{"name":"vendor-product-metrics","description":"Vendor Central sales per product, split by manufacturing and sourcing, aggregated from the account's report history. Requires `catalog:read`."},{"name":"pnl","description":"The authenticated account's P&L with product cost (COGS) and own expenses down to net profit, from the same data as the Rentabilidad screen. Unlike every other resource in this API, amounts ARE converted into the `currency` you request. Free and Guru plans receive the same shape with product cost always `0` and no own expenses. Requires `catalog:read`."},{"name":"expenses","description":"Own expenses of the account (agency, software, packaging...), which the P&L subtracts down to net profit. Reading requires `catalog:read`; writing, `costs:write`. Business and Master plans only."},{"name":"expense-categories","description":"Categories own expenses are grouped by: the standard ones and the account ones. Reading requires `catalog:read`; writing, `costs:write`. Business and Master plans only."},{"name":"product-brands","description":"Brands present in the authenticated account's catalog. Requires `catalog:read`. Sparse fieldsets use `fields[brand]` — keyed by the entity type (`brand`, the same one `expand[]=brand` and a product's `brand` field use), not by the resource name."},{"name":"countries","description":"Amazon marketplace countries. Requires `catalog:read`."},{"name":"currencies","description":"Convert an amount between currencies with the daily exchange rate Epinium uses. A global reference table, like `countries`. Requires `catalog:read`."},{"name":"clusters","description":"The authenticated account's keyword clusters. Requires `catalog:read`; creating and editing them requires `catalog:write`."},{"name":"listing-updates","description":"Prepare, validate and apply changes to the attributes of seller and vendor listings, in bulk, from a customer file. Preparing, validating and reading the state of an apply require `catalog:read`; applying requires `catalog:write`, runs in the background and saves the changes as pending: nothing is sent to Amazon until someone publishes them."},{"name":"listing-drafts","description":"New seller offers on products that already exist in the Amazon catalog: find the product by ASIN, EAN, UPC or GTIN, validate the offer and save it as pending. Finding, validating and listing require `catalog:read`; saving and discarding require `catalog:write`. Validation reports in `amazon.missing` what Amazon requires for that product and the offer lacks; saving repeats Amazon's validation and refuses with 400 an offer Amazon would reject. Nothing is sent to Amazon until someone presses Publish in the app."},{"name":"pending-listing-changes","description":"The listing changes saved in Epinium and pending to publish to Amazon, the same ones the Review and publish table shows, without the rows already uploading, and publishing them. Listing requires `catalog:read`; `include_total=true` gives the size of the whole set. Publishing requires `catalog:write` and `catalog:publish`: it sends to Amazon the chosen changes and new listings by the same path as Publish in the app, cannot be undone, and answers 409 `selection_changed` without publishing anything when the selection is no longer `expected_count`. Follow the publication with `GET /v1/publications/{id}`."},{"name":"publications","description":"Each publication of listing changes to Amazon and how it is going per country, the same as the Publications panel of the app: accepted, rejected and pending counts, rejections with their issues, and new listings accepted by Amazon that are still being imported into Epinium. A publication is in progress while `in_flight` is true; importing can take up to about two hours. Requires `catalog:read`. `include_total=true` gives the size of the whole set."},{"name":"listing-files","description":"Upload a spreadsheet of listing changes once, or store the rows written in a chat as one, to prepare, validate and apply it by `file_id`. Requires `catalog:read`; storing rows written in a chat requires `catalog:write`. Files are kept 7 days."},{"name":"listing-images","description":"Upload a product image to use as the `media_location` of an Amazon image attribute (`main_product_image_locator`, `other_product_image_locator_1` to `_8`, `swatch_product_image_locator`). JPEG, PNG, GIF or TIFF, up to 8 MB. Requires `catalog:write`. Images are kept 30 days."},{"name":"prompts","description":"The authenticated account's custom prompts: the instructions Epinium's AI follows when it writes listing content, linked to keyword clusters. Requires `catalog:read`; creating and editing them requires `catalog:write`."},{"name":"brand-identities","description":"The authenticated account's brand identity (Settings > Corporate identity in the app): name, category, the brand's and its competitors' websites, a profile per competitor with its threat level, free observations as plain text and the catalog brands it covers. Not the catalog brands of `product-brands`. Requires `catalog:read`; creating and editing them requires `catalog:write`. No delete, logo or files."},{"name":"campaigns","description":"The authenticated account's advertising campaigns. Requires `campaigns:read`."},{"name":"campaign-metrics","description":"Advertising performance per campaign, aggregated from the account's report history. Requires `campaigns:read`."},{"name":"portfolios","description":"The authenticated account's portfolios and the budget cap each one puts on its campaigns. Requires `campaigns:read`; writing requires `campaigns:write`."},{"name":"adgroups","description":"The authenticated account's ad groups. Requires `campaigns:read`."},{"name":"adgroup-metrics","description":"Performance per ad group over a date range."},{"name":"targets","description":"The authenticated account's advertising targets. Requires `campaigns:read`."},{"name":"target-metrics","description":"Performance per target, with its keyword and match type."},{"name":"product-ads","description":"The authenticated account's advertising product ads. Requires `campaigns:read`."},{"name":"product-ad-metrics","description":"Performance per advertised product, with its ASIN."},{"name":"search-terms","description":"The authenticated account's advertising search terms. Requires `campaigns:read`."},{"name":"search-term-metrics","description":"Performance per shopper query, with its text and matching target."},{"name":"advertising-changes","description":"Every change Epinium pushed to Amazon for the authenticated account - from the app, a workflow, an internal job or this API - including the ones Amazon rejected. Requires `campaigns:read`."},{"name":"tasks","description":"The authenticated account's tasks. Requires `tasks:read`."},{"name":"task-items","description":"Individual suggestions within a task. Requires `tasks:read`."},{"name":"skills","description":"Catalog of validated marketing playbooks, served from memory and shared by every account. Requires `skills:read`."},{"name":"workflows","description":"The authenticated account's automation workflows, the campaigns they process and those campaigns' performance. Requires `workflows:read`."},{"name":"workflow-templates","description":"The catalogue of automations Epinium publishes, and the route to create this account's own copy of one. Which templates an account sees depends on its feature flags. Requires `workflows:read`; instantiating also requires `workflows:write`."}],"servers":[],"components":{"schemas":{},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Client API key (POST /api-keys). Send as `Authorization: Bearer epk_live_...`."}}},"security":[{"bearer":[]}]}