Interface SyncCatalogsSuccess

Success response - sync operation processed catalogs (may include per-catalog failures)

interface SyncCatalogsSuccess {
    status?: "completed";
    dry_run?: boolean;
    catalogs: {
        catalog_id: string;
        catalog_generation?: string;
        action: CatalogAction;
        platform_id?: string;
        item_count?: number;
        items_approved?: number;
        items_pending?: number;
        items_rejected?: number;
        item_issues?: {
            item_id: string;
            status: CatalogItemStatus;
            reasons?: string[];
        }[];
        last_synced_at?: string;
        next_fetch_at?: string;
        changes?: string[];
        errors?: Error[];
        warnings?: string[];
    }[];
    item_availability_updates?: {
        request_index: number;
        catalog_id: string;
        catalog_generation: string;
        item_id: string;
        action: "suppress"
        | "restore";
        status: "unchanged" | "failed" | "applied";
        availability?: "active" | "suppressed";
        overlay_revision?: number;
        expires_at?: string;
        applied_at?: string;
        errors?: [Error, ...Error[]];
        ext?: ExtensionObject;
    }[];
    item_availability_states?: {
        request_index: number;
        catalog_id: string;
        catalog_generation: string;
        item_id: string;
        status: "failed"
        | "found";
        availability?: "active" | "suppressed";
        overlay_revision?: number;
        expires_at?: string;
        updated_at?: string;
        errors?: [Error, ...Error[]];
        ext?: ExtensionObject;
    }[];
    sandbox?: boolean;
    context?: ContextObject;
    ext?: ExtensionObject;
}

Index

Properties

status? dry_run? catalogs item_availability_updates? item_availability_states? sandbox? context? ext?

Properties

`Optional`status

status?: "completed"

Availability and synchronous catalog results are terminal and complete.

`Optional`dry_run

dry_run?: boolean

Whether this was a dry run (no actual changes made)

catalogs

catalogs: {
    catalog_id: string;
    catalog_generation?: string;
    action: CatalogAction;
    platform_id?: string;
    item_count?: number;
    items_approved?: number;
    items_pending?: number;
    items_rejected?: number;
    item_issues?: {
        item_id: string;
        status: CatalogItemStatus;
        reasons?: string[];
    }[];
    last_synced_at?: string;
    next_fetch_at?: string;
    changes?: string[];
    errors?: Error[];
    warnings?: string[];
}[]

Results for each catalog processed. Items with action='failed' indicate per-catalog validation/processing failures, not operation-level failures.

Type Declaration

catalog_id: string
Catalog ID from the request
Optionalcatalog_generation?: string
Opaque token for this catalog incarnation. Sellers declaring catalog_item_availability_updates MUST return it for every accessible buyer-managed catalog result, including discovery. It remains stable across ordinary upserts and feed refreshes, changes after deletion and recreation, and is never reused for the same resolved account and catalog_id.

Min Length
1

Max Length
255
action: CatalogAction
Optionalplatform_id?: string
Platform-specific ID assigned to the catalog
Optionalitem_count?: number
Total number of items in the catalog after sync. Required when action is 'created', 'updated', or 'unchanged'. Omitted on 'failed' and 'deleted'.

Minimum
0
Optionalitems_approved?: number
Number of items approved by the platform. Populated when the platform performs item-level review.

Minimum
0
Optionalitems_pending?: number
Number of items pending platform review. Common for product catalogs where items must pass content policy checks.

Minimum
0
Optionalitems_rejected?: number
Number of items rejected by the platform. Check item_issues for rejection reasons.

Minimum
0
Optionalitem_issues?: { item_id: string; status: CatalogItemStatus; reasons?: string[] }[]
Per-item issues reported by the platform (rejections, warnings). Only present when the platform performs item-level review.
Optionallast_synced_at?: string
ISO 8601 timestamp of when the most recent sync was accepted by the platform

Format
date-time
Optionalnext_fetch_at?: string
ISO 8601 timestamp of when the platform will next fetch the feed URL. Only present for URL-based catalogs with update_frequency.

Format
date-time
Optionalchanges?: string[]
Field names that were modified (only present when action='updated')
Optionalerrors?: Error[]
Validation or processing errors (only present when action='failed')
Optionalwarnings?: string[]
Non-fatal warnings about this catalog

`Optional`item_availability_updates

item_availability_updates?: {
    request_index: number;
    catalog_id: string;
    catalog_generation: string;
    item_id: string;
    action: "suppress" | "restore";
    status: "unchanged" | "failed" | "applied";
    availability?: "active" | "suppressed";
    overlay_revision?: number;
    expires_at?: string;
    applied_at?: string;
    errors?: [Error, ...Error[]];
    ext?: ExtensionObject;
}[]

Acknowledgements for item_availability_updates. The array length MUST equal the request array length; entry N MUST have request_index N, occupy position N, and exactly echo catalog_id, catalog_generation, item_id, and action from request entry N. Buyers MUST reject the response as non-conformant if count, ordering, request_index, or echoed identity differs. Lenient-mode failures stay in their request positions. In strict mode, any per-entry failure instead produces the operation-level error branch before mutation and this array is absent.

Type Declaration

request_index: number
Zero-based index of the corresponding item_availability_updates entry.
catalog_id: string
Catalog ID from the request.
catalog_generation: string
Catalog generation from the request.
item_id: string
Item ID from the request.
action: "suppress" | "restore"
Action from the request.
status: "unchanged" | "failed" | "applied"
applied means the requested overlay transition completed, including replacement or removal of an existing expires_at; unchanged means the item was already in the requested buyer-availability state with the same expiry; failed means no transition was applied.
Optionalavailability?: "active" | "suppressed"
Persisted buyer-authored state after an applied or unchanged result.
Optionaloverlay_revision?: number
Persisted state revision after an applied or unchanged result. Applied increments the request's expected_overlay_revision exactly once; unchanged preserves it.
Optionalexpires_at?: string
Persisted expiry after this update, present only for a suppressed state with an expiry.
Optionalapplied_at?: string
Seller timestamp when the buyer-availability state took effect. Required for applied. Optional for unchanged when the seller knows the timestamp of the already-persisted state.
Optionalerrors?: [Error, ...Error[]]
Why this item update failed. Required when status is failed.

Min Items
1
Optionalext?: ExtensionObject

`Optional`item_availability_states

item_availability_states?: {
    request_index: number;
    catalog_id: string;
    catalog_generation: string;
    item_id: string;
    status: "failed" | "found";
    availability?: "active" | "suppressed";
    overlay_revision?: number;
    expires_at?: string;
    updated_at?: string;
    errors?: [Error, ...Error[]];
    ext?: ExtensionObject;
}[]

Current-state results for item_availability_queries, evaluated after updates in a mixed request. The array length MUST equal the request query length; entry N MUST have request_index N, occupy position N, and exactly echo catalog_id, catalog_generation, and item_id. Buyers MUST reject any mismatch. A replayed response is historical; use a fresh query idempotency_key before treating it as current after time-dependent expiry or catalog deletion/recreation.

Type Declaration

request_index: number
Zero-based index of the corresponding item_availability_queries entry.
catalog_id: string
catalog_generation: string
item_id: string
status: "failed" | "found"
found returns current state; failed means the reference could not be read.
Optionalavailability?: "active" | "suppressed"
Current buyer-authored overlay state. active does not imply seller approval or delivery eligibility.
Optionaloverlay_revision?: number
Current optimistic-concurrency token. Revision 0 is the initial active state. Every applied suppress, applied restore, and automatic expiry increments it exactly once; unchanged updates, reads, and idempotent replays do not increment it.
Optionalexpires_at?: string
Current automatic expiry, present only while availability is suppressed with an expiry.
Optionalupdated_at?: string
Seller timestamp of the state represented by overlay_revision.
Optionalerrors?: [Error, ...Error[]]
Min Items
1
Optionalext?: ExtensionObject

`Optional`sandbox

sandbox?: boolean

When true, this response contains simulated data from sandbox mode.

`Optional`context

context?: ContextObject

`Optional`ext

ext?: ExtensionObject

Interface SyncCatalogsSuccess

Index

Properties

Properties

Optionalstatus

Optionaldry_run

catalogs

Type Declaration

catalog_id: string

Optionalcatalog_generation?: string

Min Length

Max Length

action: CatalogAction

Optionalplatform_id?: string

Optionalitem_count?: number

Minimum

Optionalitems_approved?: number

Minimum

Optionalitems_pending?: number

Minimum

Optionalitems_rejected?: number

Minimum

Optionalitem_issues?: { item_id: string; status: CatalogItemStatus; reasons?: string[] }[]

Optionallast_synced_at?: string

Format

Optionalnext_fetch_at?: string

Format

Optionalchanges?: string[]

Optionalerrors?: Error[]

Optionalwarnings?: string[]

Optionalitem_availability_updates

Type Declaration

request_index: number

catalog_id: string

catalog_generation: string

item_id: string

action: "suppress" | "restore"

status: "unchanged" | "failed" | "applied"

Optionalavailability?: "active" | "suppressed"

Optionaloverlay_revision?: number

Optionalexpires_at?: string

Optionalapplied_at?: string

Optionalerrors?: [Error, ...Error[]]

Min Items

Optionalext?: ExtensionObject

Optionalitem_availability_states

Type Declaration

request_index: number

catalog_id: string

catalog_generation: string

item_id: string

status: "failed" | "found"

Optionalavailability?: "active" | "suppressed"

Optionaloverlay_revision?: number

Optionalexpires_at?: string

Optionalupdated_at?: string

Optionalerrors?: [Error, ...Error[]]

Min Items

Optionalext?: ExtensionObject

Optionalsandbox

Optionalcontext

Optionalext

Settings

On This Page

`Optional`status

`Optional`dry_run

`Optional`catalog_generation?: string

`Optional`platform_id?: string

`Optional`item_count?: number

`Optional`items_approved?: number

`Optional`items_pending?: number

`Optional`items_rejected?: number

`Optional`item_issues?: { item_id: string; status: CatalogItemStatus; reasons?: string[] }[]

`Optional`last_synced_at?: string

`Optional`next_fetch_at?: string

`Optional`changes?: string[]

`Optional`errors?: Error[]

`Optional`warnings?: string[]

`Optional`item_availability_updates

`Optional`availability?: "active" | "suppressed"

`Optional`overlay_revision?: number

`Optional`expires_at?: string

`Optional`applied_at?: string

`Optional`errors?: [Error, ...Error[]]

`Optional`ext?: ExtensionObject

`Optional`item_availability_states

`Optional`availability?: "active" | "suppressed"

`Optional`overlay_revision?: number

`Optional`expires_at?: string

`Optional`updated_at?: string

`Optional`errors?: [Error, ...Error[]]

`Optional`ext?: ExtensionObject

`Optional`sandbox

`Optional`context

`Optional`ext