Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Manage local store inventory

You can provide and manage inventory metadata in your catalogs for products in physical store locations. Your catalogs can display price and availability for items in individual stores.
The process involves two major steps:
  • Setting up physical store metadata, including store names and locations
  • Setting up metadata for inventory, including alternate pricing, availability, and ad links for items, organized by store

Step 1: Set up local stores

Currently, we support adding up to 10,000 stores for a single catalog.
POST
Create local stores
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Parameters to keep in mind

Create local store
Parameter
Description
catalog_id

string
Required
Unique identifier for the catalog where you want to place the inventory ad(s).
To fetch catalog IDs:
GET
List catalogs
store_code

string
Required
Provide the merchant's code for the local store, unique within the merchant's catalog.
name

string
Required
Name of the store selling the inventory.
country

string
Required
Select the two-digit ISO 3166-1 alpha-2 code for the country where the store is located.
You can provide additional, optional location-related information about the store, such as address, city, and zip code. See the endpoint reference page.

Example request

curl -X POST "https://api.pinterest.com/v5/catalogs/local/stores/batch" \
  -H "Authorization: Bearer pina_ABCD1234..." \
  -H "Content-Type: application/json" \
  -d '[
    {
        "store_code": "store_1",
        "name": "Sunnyvale Store",
        "address_primary": "123 Johnson St",
        "address_secondary": "Suite 100",
        "city": "Sunnyvale",
        "region": "CA",
        "postal_code": "94043",
        "country": "US",
        "latitude": -30.21,
        "longitude": 50.45
    },
    {
        "store_code": "store_2",
        "name": "San Francisco Store",
        "address_primary": "321 Hayes St",
        "city": "San Franciscco",
        "region": "CA",
        "postal_code": "94114",
        "country": "US",
        "latitude": -30.00,
        "longitude": 49.30
    }
  ]'

Response

A successful request returns a JSON object containing all the metadata that you sent in the request. See the endpoint reference page.

Step 2: Add inventory for stores

Add batches of inventory items to a catalog, organized by the stores where the items can be purchased.
POST
Operate on local inventory item batch
With this endpoint, you manage all local store inventory batch operations:
CREATE
UPSERT
UPDATE
DELETE
The use case in this guide is for creating inventory involves two of these operations, as seen in the following table. Learn about all catalog batch operations
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters to consider

Create store parameters
Parameter
Description
operation

string
Required
Pass
CREATE
to add new items if you are certain that items do not exist already in the catalog. Best for real-time additions.
Pass
UPSERT
to add new items or update items if you are uncertain whether items exist already in the catalog. You must include all attributes in the API request, even if you are only modifying a subset of attributes.
Pass
UPDATE
to update items if you are certain that they exist already in the catalog. Best for real-time item modifications. You can modify specific attributes while leaving other attributes unchanged.
Pass
DELETE
to remove all merchant data for existing items.
item_id

string
Required
Provide your unique identifier for the product.
Note that
item_id
and
store_code
in combination identify a unique local inventory item.
store_code

string
Required
Provide the code for your store selling the inventory, unique within your catalog.
Note that
item_id
and
store_code
in combination identify a unique local inventory item.
name

string
Required
Provide the name of the store selling the inventory.
attributes

object
Required for
CREATE
UPSERT
and
UPDATE
operations
Container for metadata about the product item.
attributes.price

string
Required for
CREATE
and
UPSERT

Optional for
UPDATE
Provide the numeric amount and ISO 4217 currency code.
Example:
50 EUR
25 USD

If you do not provide a currency code, the default is
USD
.
attributes.sale_price

string
Optional
Provide the numeric amount and and ISO 4217 currency code.
Example:
50 EUR
25 USD

If you do not provide a currency code, the default is
USD
.
attributes.availability

string
Required for
CREATE
and
UPSERT

Optional for
UPDATE
Select whether the item is
in_stock
or
out_of_stock
.
Or, if the item is not yet available but can be preordered, select
preorder
.
attributes.ad_link

string
Optional
Provide a hyperlink to the ad on your site.

Example request

curl -X POST "https://api.pinterest.com/v5/catalogs/local/inventory_items/batch" \
  -H "Authorization: Bearer pina_1234ABCD..." \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
        {
            "operation": "CREATE",
            "item_id": "local_item_5_7_1",
            "store_code": "store_1",
            "attributes": {
                "price": "29.99 USD",
                "sale_price": "24.99 USD",
                "availability": "in stock",
                "ad_link": "https://examplelink1.com"
            }
        },
        {
            "operation": "CREATE",
            "item_id": "local_item_5_7_1",
            "store_code": "store_2",
            "attributes": {
                "price": "39.99 USD",
                "sale_price": "30.99 USD",
                "availability": "out of stock",
                "ad_link": "https://examplelink2.com"
            }
        }
    ]
  }'

Response fields to consider

The response to each batch request includes a
batch_id
and
status
for the overall API request itself:
Status of overall request
Request statusDescription
PROCESSING
Ingestion of the entire batch is happening asynchronously.
FAILED
The endpoint did not ingest any items in the batch request because of an error or issue with the request itself or with items in the batch.
COMPLETED
The ingestion process completed, and at least one item in the batch was ingested successfully.
The response also returns a
status
for each each individual item included in the batch:
Status of individual items
Item statusDescription
PROCESSING
Item is being processed asynchronously.
FAILURE
Ingetion of the item failed.
SUCCESS
The item was ingested successfully.
An ingested item may return a
warning
that identifies an issue with its data that did not prevent ingestion but should be corrected for the quality of the catalog.
The entire batch request may complete or continue processing even though individual items failed and were not ingested.
The entire batch request may complete or continue processing even though individual items failed and were not ingested.
See the following response fields to understand how batch operation request is progressing.
Create inventory response
Field
Description
batch_id

string
Required
Unique identifier of the batch request.
Use it to track whether the request has completed, failed, or is still in progress.
See Monitor the status of items in a batch operation.
item_id

string
Required
Provide your unique unique identifier for the product.
status

string
Required
Status of the operation specified in the request.
See the status table at the top of this section.
operation_results

array of objects
Required
Container for information about each item included in the batch operation.
operation_results.

item_id

object
Required
Identifer for an inventory item included in the batch operation.
operation_results.

store_code

object
Required
Code for your store selling the item in parent object.
operation_results.errors

array of objects
Required
Container for information about errors causing operation to fail for the inventory item.
operation_results.errors

attribute

string
Optional
Inventory attribute of the affected item, such as
price
or
availability
.
operation_results.errors.

code

string
Required
Event code for the error.
operation_results.errors.

message

string
Required
Explanation of the error
operation_results.warnings.

array of objects
Required
Container for information about warnings for issues that do not cause the operation to fail, but should be addressed in case they cause other potential problems.
Structure and child objects are similar to those of
errors
.

Example response

Typically right after you submit a request, the response shows validation errors and a
PROCESSING
status.
{
  "batch_id": "6895362920532313825",
  "created_time": "2026-02-05T02:04:00.540000",
  "status": "PROCESSING",
  "operation_results": [
    {
      "supplemental_type": "LOCAL_INVENTORY",
      "item_id": "local_item_5_7_1",
      "store_code": "store_1",
      "errors": [],
      "warnings": [],
      "status": "PROCESSING"
    },
    {
      "supplemental_type": "LOCAL_INVENTORY",
      "item_id": "local_item_5_7_1",
      "store_code": "store_2",
      "errors": [
        {
          "attribute": "PRICE",
          "code": 10102,
          "message": "Some local inventory product data was not published due to incorrect price formatting. Update the prices and ensure that the values are formatted using the standard ISO-4217 code for your currency. Examples: 1.00USD"
        }
      ],
      "warnings": [],
      "status": "FAILURE"
    }
  ]
}

Monitor the status of items in a batch operation

You can see which inventory items have been validated for ingestion at any time.
GET
Get supplemental items batch status

Request parameters to keep in mind

Get inventory operation status
Parameter
Description
catalog_id

string
Required
Unique identifier for the catalog where attempted to place the inventory items.
batch_id

string
Required
Unique identifer for the batch operation request that you are inquiring about.
Returned by the endpoint when you sent the batch operation request.

Example request

curl -X GET "https://api.pinterest.com/v5/catalogs/supplemental_items/batch/6895362920532313825" \
  -H "Authorization: Bearer pina_ABCD1234..." \
  -H "Content-Type: application/json"

Response structure

A successful request returns the same objects and structure as the response for the the batch operation request.

Example response

{
  "batch_id": "6895362920532313825",
  "created_time": "2026-02-05T02:04:00",
  "status": "COMPLETED",
  "operation_results": [
    {
      "supplemental_type": "LOCAL_INVENTORY",
      "item_id": "local_item_5_7_1",
      "store_code": "store_1",
      "status": "SUCCESS"
    },
    {
      "supplemental_type": "LOCAL_INVENTORY",
      "item_id": "local_item_5_7_1",
      "store_code": "store_2",
      "status": "FAILURE",
      "errors": [
        {
          "attribute": "PRICE",
          "code": 10102,
          "message": "Some local inventory product data was not published due to incorrect price formatting. Update the prices and ensure that the values are formatted using the standard ISO-4217 code for your currency. Examples: 1.00USD"
        }
      ]
    }
  ],
  "completed_time": "2026-02-05T02:04:01"
}
Was this page helpful?