API
Start Free Trial
API docs by Redocly

MerchJar Public API (v5)

Download OpenAPI specification:

The contract for the customer-facing MerchJar Public API. All paths in this document are relative to the server URL.

Getting started

Base URL

All requests use https://app.merchjar.com/api/v5.

Authentication

Send a provisioned MerchJar API key with every request:

curl https://app.merchjar.com/api/v5/profiles \
  -H 'Authorization: Bearer mj_live_…'

Create and manage API keys in Settings > API Keys. The full key is shown only once when you create it. Start with GET /profiles to discover the profile IDs available to the key.

Scopes

API keys are limited by scopes. Every operation lists its required scope in x-merchjar-required-scope; a key without that scope receives 403 Forbidden.

  • profiles:read: list accessible Amazon Advertising profiles
  • segments:read: list, retrieve, and manage segment schedules
  • segments:write: create, update, and delete segments and schedules
  • segments:preview: preview segment results
  • segments:validate: validate a segment definition
  • audit_logs:read: list audit logs and audit-log items
  • history:read: retrieve entity change history
  • campaigns:write: create campaigns
  • ad_groups:write: create ad groups
  • ads:write: create product ads
  • targets:write: create targets
  • negative-targets:write: create negative product targets
  • custom_fields:read: read custom-field catalogs, values, and CSV exports
  • custom_fields:write: manage custom-field definitions, values, and CSV imports

Rate limits and retries

Use the response headers to make retry decisions; limits are enforced before the operation runs.

Request type Limit Identity On exhaustion
Standard API operations 1,200 requests per minute by default; an API key may have a configured override API key 429 with Retry-After; standard rate limit headers appear on successful and rate limited responses
POST /segments/preview In addition to the standard limit: a 3-request burst that refills one request every 2 seconds by default Account, shared across its API keys 429 with Retry-After; the rate limit headers report the preview-admission bucket
Campaign, ad-group, product-ad, and target creation No standard rate limit middleware currently Not applicable These endpoints do not emit the standard rate limit headers or standard 429/503 rate limit responses

Retry a 429 after the supplied Retry-After value. Retry a 503 only when that response includes Retry-After; otherwise investigate before retrying.

Compatibility

MerchJar makes additive, backward-compatible changes within v5. A breaking change uses a new API version and is documented in the reference before release. Deprecated operations remain documented with migration guidance and a removal date.

Errors

Handled API errors use a JSON envelope with error.code and error.message. Use the HTTP status to choose the next action: correct 400 requests, replace invalid or revoked 401 keys, request the required scope after 403, retry 429 after Retry-After, and retry only 503 responses that include Retry-After.

Profiles

List profiles available to your API key.

List profiles

Returns profiles owned by the API key's user. This operation does not require a profileid header; it is the operation used to discover profile IDs for later profile-scoped requests.

Authorizations:
API-Key

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Segments

Validate, preview, and manage segments.

Validate a segment trigger

Compiles a Segment DSL trigger without executing it. profile_id is optional unless the trigger references custom fields; when supplied, the API key must own that profile.

Authorizations:
API-Key
Request Body schema: application/json
required
trigger
required
string non-empty

Segment DSL expression to compile.

ad_type
required
string non-empty

Segment entity type. Input is case- and separator-insensitive; see the endpoint description for supported values.

profile_id
string (NumericString) ^[1-9][0-9]*$

Required when validating a trigger that references custom fields.

Responses

Request samples

Content type
application/json
{
  • "trigger": "string",
  • "ad_type": "string",
  • "profile_id": "9007199254740993"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "variables": { }
}

Preview segment matches

Evaluates a Segment DSL trigger for a profile without persisting a segment. Preview rows depend on ad_type; every returned field whose name ends in _id is serialized as a decimal string. In addition to the API-key per-minute limiter, preview uses an account-level burst-admission limiter.

Authorizations:
API-Key
Request Body schema: application/json
required
profile_id
required
string (NumericString) ^[1-9][0-9]*$

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

trigger
required
string non-empty

Segment DSL expression.

ad_type
required
string non-empty

One of campaigns, ad_groups, ads (or accepted alias product_ads), keywords, targets, keywords_and_targets, search_terms, placements, or a negative type. Input is case- and separator-insensitive. Negative types are preview-only.

action
required
string non-empty

One of set_state, set_budget, set_default_bid, set_bid, or create_negatives. Input is case- and separator-insensitive.

action_params
required
object

Action parameters. For set_state, value must be a number or numeric string (default 2). For set_budget, set_default_bid, and set_bid, direction defaults to set-to-$, value defaults to 0, and source defaults to value; source: variable makes value a DSL variable name. create_negatives accepts an empty object.

page
integer >= 1
Default: 1
per_page
integer [ 1 .. 100 ]
Default: 25

Responses

Request samples

Content type
application/json
{
  • "profile_id": "9007199254740993",
  • "trigger": "string",
  • "ad_type": "string",
  • "action": "string",
  • "action_params": { },
  • "page": 1,
  • "per_page": 25
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    },
  • "totals": {
    },
  • "meta": {
    }
}

List segments

Authorizations:
API-Key
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Amazon Advertising profile ID owned by the API key.

Responses

Response samples

Content type
application/json
{
  • "data": [ ]
}

Create a segment

Creates a v2 segment for the body profile_id; it must belong to the API key. Run POST /segments/validate and POST /segments/preview first to check the trigger and matching entities. Negative segment types can be previewed but cannot be persisted.

Authorizations:
API-Key
Request Body schema: application/json
required
profile_id
required
string (NumericString) ^[1-9][0-9]*$

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

name
required
string [ 1 .. 255 ] characters
trigger
required
string non-empty
ad_type
required
string non-empty

A writable ad type: campaigns, ad_groups, ads (or accepted alias product_ads), keywords, targets, keywords_and_targets, search_terms, or placements. Input is case- and separator-insensitive.

action
required
string non-empty

set_state, set_budget, set_default_bid, set_bid, or create_negatives. Input is case- and separator-insensitive.

action_params
object
Default: {}

See preview action_params semantics. Unknown properties are ignored by the request parser.

frequency
string
Default: "daily"

Canonical modes are after_every_data_sync, daily, weekly, monthly, and manual. Input is case- and separator-insensitive; manually is an accepted alias for manual. Re-applying weekly or monthly resets its schedule anchor to today.

enabled
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "profile_id": "9007199254740993",
  • "name": "string",
  • "trigger": "string",
  • "ad_type": "string",
  • "action": "string",
  • "action_params": { },
  • "frequency": "daily",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve segment

Authorizations:
API-Key
path Parameters
id
required
string^[+-]?[0-9]+$

Segment ID. The implementation parses a signed base-10 bigint; successful segment IDs are positive decimal strings.

header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Amazon Advertising profile ID owned by the API key.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a segment

Updates only supplied fields. Updating ad_type revalidates the existing trigger if no trigger is supplied. Negative segment types cannot be persisted. paused: true pauses future scheduled runs without disabling the segment; enabled: false also skips future open runs.

Authorizations:
API-Key
path Parameters
id
required
string^[+-]?[0-9]+$

Segment ID. The implementation parses a signed base-10 bigint; successful segment IDs are positive decimal strings.

header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Amazon Advertising profile ID owned by the API key.

Request Body schema: application/json
required
name
string [ 1 .. 255 ] characters
trigger
string non-empty
ad_type
string non-empty

Writable segment ad type; input is case- and separator-insensitive.

action
string non-empty

set_state, set_budget, set_default_bid, set_bid, or create_negatives; input is case- and separator-insensitive.

action_params
object

See preview action_params semantics.

frequency
string

after_every_data_sync, daily, weekly, monthly, or manual; input is case- and separator-insensitive and manually aliases manual. A non-manual mode conflicts with an existing clock schedule.

enabled
boolean
paused
boolean

Sets or clears the segment pause timestamp. true skips future open scheduled runs.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "trigger": "string",
  • "ad_type": "string",
  • "action": "string",
  • "action_params": { },
  • "frequency": "string",
  • "enabled": true,
  • "paused": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a segment

Disables the segment, marks it deleted, clears its next schedule cursor, and skips future open scheduled runs.

Authorizations:
API-Key
path Parameters
id
required
string^[+-]?[0-9]+$

Segment ID. The implementation parses a signed base-10 bigint; successful segment IDs are positive decimal strings.

header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Amazon Advertising profile ID owned by the API key.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

List schedule timezones

Returns the timezone choices for a segment owned by the API-key profile.

Authorizations:
API-Key
path Parameters
id
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740997

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve segment schedule

Returns data: null when the owned segment has no stored clock schedule.

Authorizations:
API-Key
path Parameters
id
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740997

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

Responses

Response samples

Content type
application/json
{
  • "data": null
}

Set segment schedule

The segment must use manual frequency and cannot be a negative segment. A schedule definition is either a cron schedule (kind: cron, timezone, cron_expression) or one-time schedule (kind: once, timezone, run_once_at).

Authorizations:
API-Key
path Parameters
id
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740997

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

Request Body schema: application/json
required
One of
kind
required
any
Value: "cron"
timezone
required
string
cron_expression
required
string

Responses

Request samples

Content type
application/json
{
  • "kind": "cron",
  • "timezone": "America/Los_Angeles",
  • "cron_expression": "0 9 * * 1-5"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete segment schedule

Authorizations:
API-Key
path Parameters
id
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740997

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Preview segment schedule

Validates a proposed schedule and returns its future occurrences without saving it. The segment must use manual frequency and cannot be a negative segment.

Authorizations:
API-Key
path Parameters
id
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740997

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

Request Body schema: application/json
required
One of
kind
required
any
Value: "cron"
timezone
required
string
cron_expression
required
string

Responses

Request samples

Content type
application/json
{
  • "kind": "once",
  • "timezone": "America/Los_Angeles",
  • "run_once_at": "2026-09-01T16:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Audit logs

Review audit logs and entity changes.

List audit logs

Lists profile-scoped records of MerchJar changes. The default date window is the 30 calendar days ending today, calculated when the request is handled.

Authorizations:
API-Key
query Parameters
page
integer >= 1
Default: 1

One-based page number. Missing, non-positive, or non-numeric values fall back to 1.

per_page
integer [ 1 .. 100 ]
Default: 25

Results per page. Missing, non-positive, or non-numeric values fall back to 25; values above 100 are capped at 100.

from
string
Example: from=2026-03-01

Inclusive UTC start date. Send an ISO calendar date such as 2026-03-01; the route uses the start of that day. Defaults to 30 days ago.

to
string
Example: to=2026-03-31

Inclusive UTC end date. Send an ISO calendar date such as 2026-03-31; the route uses the end of that day. Defaults to today.

target_type
string
Enum: "campaigns" "ad_groups" "product_ads" "keywords" "targets" "campaign_negative_keywords" "negative_keywords" "negative_targets" "portfolios" "promotions" "recipes" "search_terms" "ads" "placements"

Filter by affected entity type.

source_type
string
Enum: "smart_bids" "promotion" "recipe" "bulk_action"

Filter by the type of source that initiated the audit log.

source_id
string^[1-9][0-9]*$
Example: source_id=9007199254740995

Filter by source ID. Send the ID as a decimal string so clients do not lose bigint precision.

count
string^(?:gt|gte|lt|lte|eq|neq):-?[0-9]+$|^between:...
Example: count=gt:10

Filter on meta.count: gt:N, gte:N, lt:N, lte:N, eq:N, neq:N, or between:N,M.

sort
string
Default: "-created_at"

Sort by created_at (the default) or effected_entities; prefix either with - for descending order. Unknown sort fields currently fall back to created_at.

header Parameters
profileid
required
string <= 19 characters ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

List audit log changes

Returns items only after verifying that the parent audit log belongs to the requested profile. The item data is retrieved from MerchJar's internal Laravel service and bigint identifiers are re-serialized as strings.

Authorizations:
API-Key
path Parameters
id
required
string^[1-9][0-9]*$
Example: 789

Audit-log ID as a decimal string.

query Parameters
page
integer >= 1
Default: 1

One-based page number. Missing, non-positive, or non-numeric values fall back to 1.

per_page
integer [ 1 .. 100 ]
Default: 25

Results per page. Missing, non-positive, or non-numeric values fall back to 25; values above 100 are capped at 100.

target_type
string
Enum: "campaigns" "ad_groups" "product_ads" "keywords" "targets" "campaign_negative_keywords" "negative_keywords" "negative_targets" "portfolios" "promotions" "recipes" "search_terms" "ads" "placements"

Filter item rows by target entity type.

target_id
string^[1-9][0-9]*$
Example: target_id=9007199254740997

Filter item rows by affected entity ID. Send the ID as a decimal string so clients do not lose bigint precision.

header Parameters
profileid
required
string <= 19 characters ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    },
  • "audit_log": {
    }
}

History

View bid and budget changes.

List entity changes

Returns the profile-scoped legacy bid-history stream, newest first with hash as the tie-breaker. MerchJar selects the change type from entity_type: campaign budgets, ad-group default bids, and keyword or target bids.

Authorizations:
API-Key
path Parameters
entity_type
required
string
Enum: "campaigns" "ad_groups" "keywords" "targets"
entity_id
required
string^[1-9][0-9]*$
Example: 9007199254740997

Positive PostgreSQL-signed-bigint entity ID encoded as a decimal string (maximum 9223372036854775807).

query Parameters
page
integer >= 1
Default: 1

One-based page number. Missing, non-positive, or non-numeric values fall back to 1; values above 21474836 are capped.

per_page
integer [ 1 .. 100 ]
Default: 25

Results per page. Missing, non-positive, or non-numeric values fall back to 25; values above 100 are capped at 100.

header Parameters
profileid
required
string <= 19 characters ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Custom fields

Manage field definitions, values, and CSV jobs.

Import custom field CSV

Queues a CSV import for the selected entity type. The request body must be UTF-8 text/csv and no larger than 25 MiB. Set dry_run=true to validate without applying mutations.

Authorizations:
API-Key
path Parameters
entityType
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
Example: campaign
query Parameters
dry_run
boolean
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Request Body schema: text/csv
required
string

Responses

Request samples

Content type
text/csv
entity_id,field,value
9007199254740995,Priority,high

Response samples

Content type
application/json
{
  • "job": {
    }
}

Export custom field CSV

Queues a CSV export for the selected entity type.

Authorizations:
API-Key
path Parameters
entityType
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
Example: campaign
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "job": {
    }
}

Retrieve CSV job

Authorizations:
API-Key
path Parameters
jobId
required
string
Example: job_01HXYZ
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "job": {
    }
}

Cancel CSV job

Authorizations:
API-Key
path Parameters
jobId
required
string
Example: job_01HXYZ
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "job": {
    }
}

Download CSV errors

Authorizations:
API-Key
path Parameters
jobId
required
string
Example: job_01HXYZ
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
text/csv
row,error
2,invalid value

Download CSV export

Authorizations:
API-Key
path Parameters
jobId
required
string
Example: job_01HXYZ
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
text/csv
entity_id,field,value
9007199254740995,Priority,high

Retrieve field catalog

Authorizations:
API-Key
path Parameters
entityType
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
Example: campaign
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "version": "1",
  • "definitions": [ ],
  • "definition_count": 0,
  • "value_count": 0
}

Snapshot field values

Authorizations:
API-Key
path Parameters
entityType
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
Example: campaign
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Request Body schema: application/json
required
entity_ids
required
Array of strings (NumericString) non-empty [ items^[1-9][0-9]*$ ]

Responses

Request samples

Content type
application/json
{
  • "entity_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "values": [ ]
}

Create field definition

Authorizations:
API-Key
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Request Body schema: application/json
required
entity_type
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
name
required
string
description
string or null
data_type
required
integer
Enum: 1 2 3

Responses

Request samples

Content type
application/json
{
  • "entity_type": "campaign",
  • "name": "Priority",
  • "data_type": 1
}

Response samples

Content type
application/json
{
  • "definition": {
    }
}

Update field definition

Authorizations:
API-Key
path Parameters
definitionId
required
string (NumericString) ^[1-9][0-9]*$
Example: 1

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Request Body schema: application/json
required
entity_type
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
expected_version
required
string (NumericString) ^[1-9][0-9]*$

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

name
required
string
description
string or null

Responses

Request samples

Content type
application/json
{
  • "entity_type": "campaign",
  • "expected_version": "1",
  • "name": "Priority"
}

Response samples

Content type
application/json
{
  • "definition": {
    }
}

Delete field definition

Authorizations:
API-Key
path Parameters
definitionId
required
string (NumericString) ^[1-9][0-9]*$
Example: 1

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Request Body schema: application/json
required
entity_type
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
expected_version
required
string (NumericString) ^[1-9][0-9]*$

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

disable_dependants
boolean

Responses

Request samples

Content type
application/json
{
  • "entity_type": "campaign",
  • "expected_version": "1"
}

Response samples

Content type
application/json
{
  • "values": [ ]
}

List field values

Authorizations:
API-Key
path Parameters
entityType
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
Example: campaign
query Parameters
entity_id
string (NumericString) ^[1-9][0-9]*$
Example: entity_id=9007199254740995

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

entity_ids
string
Example: entity_ids=9007199254740995,9007199254740996
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "values": [ ]
}

List definition values

Authorizations:
API-Key
path Parameters
entityType
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
Example: campaign
definitionId
required
string (NumericString) ^[1-9][0-9]*$
Example: 1

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

query Parameters
limit
integer [ 1 .. 200 ]
Example: limit=100
after_entity_id
string (NumericString) ^[1-9][0-9]*$
Example: after_entity_id=9007199254740995

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "values": [ ]
}

Update field values

Authorizations:
API-Key
path Parameters
entityType
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
Example: campaign
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Request Body schema: application/json
required
required
Array of objects
source_reference
string or null <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "mutations": [
    ]
}

Response samples

Content type
application/json
{
  • "values": [ ]
}

List field value history

Authorizations:
API-Key
path Parameters
entityType
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
Example: campaign
entityId
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740995

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

query Parameters
definition_id
string (NumericString) ^[1-9][0-9]*$
Example: definition_id=1

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

limit
integer [ 1 .. 200 ]
Example: limit=100
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Responses

Response samples

Content type
application/json
{
  • "values": [ ]
}

Roll back field change

Authorizations:
API-Key
path Parameters
historyId
required
string (NumericString) ^[1-9][0-9]*$
Example: 1

A positive base-10 integer encoded as a string. Use this for profile IDs and entity IDs so values larger than JavaScript's safe integer limit retain their precision.

header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive decimal Amazon Advertising profile ID owned by the API-key user.

Request Body schema: application/json
required
entity_type
required
string (CustomFieldEntityType)
Enum: "campaign" "ad_group" "target" "ad"
expected_version
required
string or null^[1-9][0-9]*$

Responses

Request samples

Content type
application/json
{
  • "entity_type": "campaign",
  • "expected_version": "1"
}

Response samples

Content type
application/json
{
  • "values": [ ]
}

Campaign creation

Create Sponsored Products campaigns.

Create Sponsored Products campaigns

Creates between 1 and 1,000 Sponsored Products campaigns for the API-key-authorized profileid header. The request schema is strict: profile_id and every other undeclared field are rejected before MerchJar calls Amazon. The 200 response is Amazon's raw batch envelope, without a MerchJar wrapper. A success or partialSuccess result queues local projection; browse data is eventually consistent and the response does not report projection completion. An error-only Amazon envelope is also passed through, but does not queue a receipt. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This router does not currently install the API-key rate limit middleware, so it does not emit the standard rate limit headers or 429/503 rate limit responses.

Authorizations:
API-Key
header Parameters
profileid
required
string^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-...
Example: 9007199254740993

Positive PostgreSQL signed-bigint Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "campaigns": [
    ]
}

Response samples

Content type
application/json
{
  • "error": [
    ],
  • "success": [
    ],
  • "partialSuccess": [
    ]
}

Ad group creation

Create Sponsored Products ad groups.

Create ad groups

Creates between 1 and 1,000 Sponsored Products ad groups for the API-key-authorized profileid header. The request schema is strict: profile_id and every other undeclared field are rejected before MerchJar calls Amazon. campaignId is forwarded directly to Amazon; MerchJar does not locally check that the campaign exists or is compatible. The 200 response is Amazon's raw batch envelope, without a MerchJar wrapper. A success or partialSuccess result queues local projection; browse data is eventually consistent and the response does not report projection completion. An error-only Amazon envelope is also passed through, but does not queue a receipt. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This router does not currently install the API-key rate limit middleware, so it does not emit the standard rate limit headers or 429/503 rate limit responses.

Authorizations:
API-Key
header Parameters
profileid
required
string^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-...
Example: 9007199254740993

Positive PostgreSQL signed-bigint Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "adGroups": [
    ]
}

Response samples

Content type
application/json
{
  • "error": [
    ],
  • "success": [
    ],
  • "partialSuccess": [
    ]
}

Product ad creation

Create Sponsored Products ads.

Create product ads

Creates between 1 and 1,000 Sponsored Products product ads for the API-key-authorized profileid header. This is deliberately not generic unified-v1 ad creation: each item supports only PRODUCT_AD with exactly one productCreative / advertisedProduct creative. The request schema is strict: profile_id, marketplace/global-store identity, headline, and every other undeclared field are rejected before MerchJar calls Amazon. The 200 response is Amazon's raw batch envelope, without a MerchJar wrapper. A success or partialSuccess result queues local projection; browse data is eventually consistent and the response does not report projection completion. An error-only Amazon envelope is also passed through, but does not queue a receipt. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This router does not currently install the API-key rate limit middleware, so it does not emit the standard rate limit headers or 429/503 rate limit responses.

Authorizations:
API-Key
header Parameters
profileid
required
string^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-...
Example: 9007199254740993

Positive PostgreSQL signed-bigint Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "ads": [
    ]
}

Response samples

Content type
application/json
{
  • "error": [
    ],
  • "success": [
    ],
  • "partialSuccess": [
    ]
}

Target creation

Create Sponsored Products targets.

Create negative targets

Creates between 1 and 1,000 negative Sponsored Products product targets for the API-key-authorized profileid header. Each target must have an ad-group parent, negative: true, targetType: PRODUCT, PRODUCT_EXACT matching, and an ASIN. The request schema is strict: unknown fields are rejected before MerchJar calls Amazon. A success or partialSuccess result queues local projection; an error-only envelope does not. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This endpoint does not install the standard API-key rate limit middleware, so it does not emit the standard rate limit headers or standard 429 or 503 rate limit responses.

Authorizations:
API-Key
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "error": [
    ],
  • "success": [
    ],
  • "partialSuccess": [
    ]
}

Create targets

Creates between 1 and 1,000 Sponsored Products targets for the API-key-authorized profileid header. The request schema is strict: unknown fields are rejected before MerchJar calls Amazon. The response is Amazon's raw batch envelope. A success or partialSuccess result queues local projection; an error-only envelope does not. MerchJar provides no idempotency guarantee and does not automatically retry creates; if the outcome is unknown, verify Amazon or the normal read state before retrying. This endpoint does not install the standard API-key rate limit middleware, so it does not emit the standard rate limit headers or standard 429 or 503 rate limit responses.

Authorizations:
API-Key
header Parameters
profileid
required
string (NumericString) ^[1-9][0-9]*$
Example: 9007199254740993

Positive Amazon Advertising profile ID owned by the API key. Send it as a decimal string, never as a JavaScript number.

Request Body schema: application/json
required
required
Array of objects or objects or objects or objects or objects or objects or objects or objects [ 1 .. 1000 ] items

One to 1,000 targets. Each target uses exactly one target type and matching target-details shape.

Responses

Request samples

Content type
application/json
{
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "success": [
    ]
}