Skip to main content
API docs by Redocly

OpenTiendas API (1.2.11)

Download OpenAPI specification:Download

OpenTiendas REST API documentation.

Brands

A Brand represents the manufacturer or commercial brand associated with products in the catalog. Brands are used for catalog organization, filtering, and SEO presentation.

Fixed fields: id

Default fields: name, internal_id, url

See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Brands

Retrieve a paginated list of brands with optional filtering and ordering.

Authorizations:
ApiKeyAuth
query Parameters
brand_ids
Array of integers

Filter brands by a comma-separated list of brand IDs. Exact match on brand.id. Max 200 IDs.

internal_ids
Array of strings

Filter brands by a comma-separated list of brand internal IDs. Exact match on brand.internal_id. Max 200 IDs.

page
integer

A page number within the paginated result set.

per_page
integer <= 100
Default: 50

Number of results to return per page.

slug
Array of strings

Filter brands by a comma-separated list of slugs. Max 200 slugs.

sort
string

Which field to use when ordering the results. Use '_asc' or '_desc' suffix to specify ascending or descending order. Valid values are: name_asc, name_desc.

Default value: name_asc

Responses

Response samples

Content type
application/json
Example
{}

Create Brand

Create a new brand with the provided details.

Authorizations:
ApiKeyAuth
Request Body schema:
required
name
required
string

Name of the brand.

internal_id
string or null

Internal ID for the brand. This alternative identifier is intended for linking it with external systems and managing it through imports or API integrations.

slug
string^[-a-zA-Z0-9_]+$

URL-friendly slug for the brand. If not provided, it will be automatically generated from the name. Updating it changes the URL and may impact SEO (links and indexed pages). Cache invalidation or page refresh may be required for the change to take effect immediately.

delivery_time_in_stock
integer >= 0

Estimated delivery time in days when the product is in stock.

delivery_time_out_of_stock
integer >= 0

Estimated delivery time in days when the product is out of stock.

image_url
string or null <uri>

URL of the brand logo image. If provided, the image will be downloaded and saved. The timeout for downloading the image is set to 5 seconds.

required
Array of objects (BrandTranslation)

Responses

Request samples

Content type
{
  • "name": "Marca de Ejemplo",
  • "internal_id": "BRAND-001",
  • "image_url": "https://external.server.com/brand_logo.jpg",
  • "delivery_time_in_stock": 1,
  • "delivery_time_out_of_stock": 3,
  • "translations": {
    }
}

Response samples

Content type
application/json
[]

Get Brand Detail

Retrieve detailed information about a specific brand by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
Example
{}

Update Brand

Update an existing brand's details.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer
Request Body schema:
name
string

Name of the brand.

internal_id
string or null

Internal ID for the brand. This alternative identifier is intended for linking it with external systems and managing it through imports or API integrations.

slug
string^[-a-zA-Z0-9_]+$

URL-friendly slug for the brand. If not provided, it will be automatically generated from the name. Updating it changes the URL and may impact SEO (links and indexed pages). Cache invalidation or page refresh may be required for the change to take effect immediately.

delivery_time_in_stock
integer >= 0

Estimated delivery time in days when the product is in stock.

delivery_time_out_of_stock
integer >= 0

Estimated delivery time in days when the product is out of stock.

image_url
string or null <uri>

URL of the brand logo image. If provided, the image will be downloaded and saved. The timeout for downloading the image is set to 5 seconds.

Array of objects (BrandTranslation)

Responses

Request samples

Content type
{
  • "name": "Other Brand Name",
  • "internal_id": "new_internal_id",
  • "translations": {
    }
}

Response samples

Content type
application/json
{}

Delete Brand

Delete a specific brand by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Categories

A Category represents a hierarchical grouping of products in the catalog. Categories are used for navigation (category pages), filtering, and SEO presentation.

Fixed fields: id

Default fields: internal_id, name, url

See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Categories

Retrieve a paginated list of categories with optional filtering and ordering.

Authorizations:
ApiKeyAuth
query Parameters
category_ids
Array of integers

Filter categories by a comma-separated list of category IDs. Exact match on category.id. Max 200 IDs.

internal_ids
Array of strings

Filter categories by a comma-separated list of category internal IDs. Exact match on category.internal_id. Max 200 IDs.

is_root_folder
boolean

Filter categories that are root folders (i.e., have no parent).

page
integer

A page number within the paginated result set.

parent_id
number

Filter categories by parent category ID.

per_page
integer <= 100
Default: 50

Number of results to return per page.

slug
string

Filter categories by a comma-separated list of slugs. Max 200 slugs.

sort
string

Which field to use when ordering the results. Use '_asc' or '_desc' suffix to specify ascending or descending order. Valid values are: name_asc, name_desc.

Default value: name_asc

status
string
Enum: "published" "unpublished"

Filter categories by publication status.

  • published - published
  • unpublished - unpublished

Responses

Response samples

Content type
application/json
Example
{}

Create Category

Create a new category with the provided details.

Authorizations:
ApiKeyAuth
Request Body schema:
required
internal_id
string or null

Internal ID for the category. This alternative identifier is intended for linking it with external systems and managing it through imports or API integrations.

image_url
string or null <uri>

URL of the category image. If provided, the image will be downloaded and saved. The timeout for downloading the image is set to 5 seconds.

parent_id
integer or null

ID of the parent category, if any. Null if this is a top-level category.

status
required
string
Enum: "published" "unpublished"

Status of the object: 'published' or 'unpublished'.

  • published - published
  • unpublished - unpublished
object

Merchant category mappings (e.g., Google taxonomy).

required
Array of objects (CategoryTranslation)

Responses

Request samples

Content type
{
  • "internal_id": "CAT-002",
  • "image_url": "https://example.com/images/new_category.jpg",
  • "parent_id": 23,
  • "status": "published",
  • "merchant_categories": {
    },
  • "translations": {
    }
}

Response samples

Content type
application/json
{}

Get Category Detail

Retrieve detailed information about a specific category by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
Example
{}

Update Category

Update an existing category's details.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer
Request Body schema:
internal_id
string or null

Internal ID for the category. This alternative identifier is intended for linking it with external systems and managing it through imports or API integrations.

image_url
string or null <uri>

URL of the category image. If provided, the image will be downloaded and saved. The timeout for downloading the image is set to 5 seconds.

parent_id
integer or null

ID of the parent category, if any. Null if this is a top-level category.

status
string
Enum: "published" "unpublished"

Status of the object: 'published' or 'unpublished'.

  • published - published
  • unpublished - unpublished
object

Merchant category mappings (e.g., Google taxonomy).

Array of objects (CategoryTranslation)

Responses

Request samples

Content type
{
  • "status": "published",
  • "merchant_categories": {
    },
  • "translations": {
    }
}

Response samples

Content type
application/json
{}

Delete Category

Delete a specific category by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Contacts (customers and subscribers)

A Contact is created when a person provides identifying information through any of the following actions:

  • Creating an order (including guest checkout)
  • Completing the account registration process
  • Subscribing to communications (e.g. newsletter)
  • Being created through import or external integration processes

A contact can be a customer, a subscriber, or both.

Other considerations:

  • Like other resources, contacts are identified by their id field. Additionally, the email and internal_id fields are also unique and cannot be duplicated across contacts.
  • A customer is a contact that has made a purchase or completed a registration; therefore, it may be registered or not, and may or may not have completed a purchase.
  • If a non-registered customer later registers using the same email address, the existing contact record is reused and retains the same id.
  • A subscriber is a contact whose marketing state (mkt_state field) is either subscribed or unsubscribed, indicating their marketing preference. Only contacts with a marketing state of subscribed are eligible to receive marketing communications.

Fixed fields: id

Default fields: internal_id, is_active, email, first_name, last_name, full_name, phone, preferred_locale

See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Contacts

Retrieve a paginated list of contacts with optional filtering and ordering.

The view parameter is required to define the subset of contacts to return (e.g. customers, subscribers).

Authorizations:
ApiKeyAuth
query Parameters
contact_ids
Array of integers

Filter contacts by a comma-separated list of contact IDs. Exact match on contact.id. Max 200 IDs.

created_at_from
string <date-time>

Filter contacts created from this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T00:00:00Z). If the time component is omitted, 00:00:00 is assumed.

created_at_to
string <date-time>

Filter contacts created up to this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T23:59:59Z). If the time component is omitted, 23:59:59 is assumed.

customer_type
string

Merchant-defined customer (contact) classification (e.g. professional, individual, sector). Selected during registration and editable by the customer. Exact case-sensitive match on contact.customer_type.

email
Array of strings

Filter contacts by a comma-separated list of emails. Max 200 emails. Exact match case-insensitive on contact.email.

internal_ids
Array of strings

Filter contacts by a comma-separated list of contact internal IDs. Exact match on contact.internal_id. Max 200 IDs.

is_active
boolean

Filter customers (contacts) by active status.

is_agreed_payment_enabled
boolean

Filters customers (contacts) with agreed payment enabled.

is_b2b
boolean

Filters B2B customers (contacts).

is_customer
boolean

Filter contacts that have made a purchase or completed a registration.

last_login_at_from
string <date-time>

Filter customers (contacts) whose last login was from this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T00:00:00Z). If the time component is omitted, 00:00:00 is assumed.

last_login_at_to
string <date-time>

Filter customers (contacts) whose last login was up to this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T23:59:59Z). If the time component is omitted, 23:59:59 is assumed.

mkt_state
string
Enum: "not_subscribed" "subscribed" "unsubscribed"

Filter customers (subscribers) by subscription state.

  • not_subscribed - not_subscribed
  • subscribed - subscribed
  • unsubscribed - unsubscribed
orders_count_min
number

Filter customers (contacts) with a minimum number of created orders.

page
integer

A page number within the paginated result set.

per_page
integer <= 100
Default: 50

Number of results to return per page.

sort
string

Which field to use when ordering the results. Use '_asc' or '_desc' suffix to specify ascending or descending order. Valid values are: email_asc, email_desc, created_at_asc, created_at_desc, last_login_at_asc, last_login_at_desc.

Default value: created_at_desc

view
required
string
Enum: "customers" "subscribers"

Which subset of contacts to return. Must be customers or subscribers.

Responses

Response samples

Content type
application/json
Example
{}

Get Contact Detail

Retrieve detailed information about a specific contact by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "internal_id": "CONT-0001",
  • "is_active": true,
  • "email": "contact@example.com",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "full_name": "Jane Doe",
  • "phone": "600123456",
  • "preferred_locale": "en-GB"
}

Jobs

A Job represents an asynchronous background task created by OpenTiendas to process heavy API operations without blocking the original request or affecting store performance.

Jobs are commonly created by bulk API operations, such as products_bulk_upsert or variants_bulk_update. When one of these operations is accepted, the API returns 202 Accepted together with a job_id. This initial response confirms that the job has been created and queued for processing. The final result is determined later, when the job is processed.

External integrations can use jobs to inspect the status, result, and processing logs of large operations. They can also subscribe to job webhooks to be notified automatically when a job reaches a final state, avoiding periodic polling.

A completed job may still contain errors. Use completed_with_errors to detect jobs where the background task finished but some records could not be processed successfully. Use the Job Logs endpoint to inspect the affected records and validation details.

Other considerations:

  • Logs are not included in the job response. Use the Job Logs endpoint to retrieve the execution log for a specific job.
  • Jobs and their logs are retained for 5 days from the creation date when completed successfully, and for 30 days when failed or completed with errors. After this period, they are automatically deleted.

Fixed fields: id

Default fields: type, status, created_at, started_at, finished_at, summary

See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Log Entries

Retrieve a paginated list of log entries for a specific job, with optional filtering and ordering. Use this endpoint to inspect processing information, warnings, and errors generated during job execution.

Jobs and their logs are retained for 5 days after creation when completed successfully, and for 30 days when failed or completed with errors. See Job Status Values for more information. After the retention period expires, they are automatically deleted.

Severity Values

Each log entry includes a severity value to indicate whether it is informational, a warning, or an error that affected processing.

Value Description
INFO Informational messages about job processing progress.
WARNING Indications of potential issues that did not prevent record processing.
ERROR Indications of issues that caused record processing to fail.
Log Codes

Each log entry includes a code to identify the specific type of issue detected during processing.

Code Description
AMBIGUOUS_MATCH More than one record matches the provided identifier.
INVALID_FIELD_VALUE A field has an invalid value. Affected field may be included in affected_fields.
INVALID_IDENTIFIER The identifier used to match the resource is missing or invalid.
MISSING_REQUIRED_FIELD A required field is missing.
NOT_FOUND No existing record was found for the provided identifier.
OTHER An unexpected error occurred during processing.
Authorizations:
ApiKeyAuth
path Parameters
job_id
required
string <uuid>
query Parameters
code
string or null
Enum: "AMBIGUOUS_MATCH" "INVALID_FIELD_VALUE" "INVALID_IDENTIFIER" "MISSING_REQUIRED_FIELD" "NOT_FOUND" "OTHER"

Filter log entries by log code. See values and descriptions.

  • AMBIGUOUS_MATCH - Ambiguous match
  • INVALID_FIELD_VALUE - Invalid field value
  • INVALID_IDENTIFIER - Invalid identifier
  • MISSING_REQUIRED_FIELD - Missing required field
  • NOT_FOUND - Not found
  • OTHER - Other
created_at_from
string <date-time>

Filter log entries created from this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T00:00:00Z). If the time component is omitted, 00:00:00 is assumed.

created_at_to
string <date-time>

Filter log entries created up to this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T23:59:59Z). If the time component is omitted, 23:59:59 is assumed.

page
integer

A page number within the paginated result set.

per_page
integer <= 500
Default: 100

Number of results to return per page.

severity
Array of strings
Items Enum: "ERROR" "INFO" "WARNING"

Filter log entries by severity. See values and descriptions.

  • INFO - Info
  • WARNING - Warning
  • ERROR - Error
sort
string

Which field to use when ordering the results. Use '_asc' or '_desc' suffix to specify ascending or descending order. Valid values are: created_at_asc, created_at_desc.

Default value: created_at_desc

Responses

Response samples

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

Get Job Detail

Retrieve detailed information about a specific job by its ID.

Status Values

The job status indicates the current processing state and whether the job finished successfully, partially, or failed.

ValueDescription
pendingJob is waiting to be processed.
runningJob is currently being processed.
doneJob has been completed and all records were processed successfully.
done_with_errorsJob has been completed but some records could not be processed successfully.
failedJob has failed and no records were processed successfully.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "0d1e1658-98c7-470b-a515-bd523cff01f7",
  • "type": "bulk_update_variants",
  • "status": "completed_with_errors",
  • "created_at": "2026-05-13T18:09:09Z",
  • "started_at": "2026-05-13T18:18:43Z",
  • "finished_at": "2026-05-13T18:19:52Z",
  • "summary": {
    }
}

Orders

An Order represents a purchase attempt created when a customer proceeds to the payment step during checkout. It records the items the customer intends to buy together with the commercial and operational information associated with that transaction. Because an order is created at the payment stage while going through the entire checkout process, a customer may generate multiple orders if the checkout process is abandoned and started again.

An order is a transactional snapshot created at that moment. The items, prices, taxes, and totals stored in the order reflect the exact state of the transaction at the time it was created and are not affected by later changes to products, variants, or pricing. Each order contains one or more order items referencing the variants selected by the customer, together with the quantities and commercial conditions applied. It also includes customer information, billing and shipping addresses, payment data, shipping details, and order totals.

Totals are always expressed in the canonical shop currency (ie. EUR).

Fixed fields: id

Default fields: created_at, payment_status, warehouse_release_status, fulfillment_status, delivery_method, locale, payment_method, payment_gateway, paid_at, fulfilled_at, canceled_at, total, shipping, fees, email

Nested objects: customer

No nested objects are included by default. Use the includes query parameter to include nested objects in the response.
See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Orders

Retrieve a paginated list of orders with optional filtering and ordering.

Authorizations:
ApiKeyAuth
query Parameters
created_at_from
string <date-time>

Filter orders created from this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T00:00:00Z). If the time component is omitted, 00:00:00 is assumed.

created_at_to
string <date-time>

Filter orders created up to this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T23:59:59Z). If the time component is omitted, 23:59:59 is assumed.

delivery_method
string (Shipping method)
Enum: "shipment" "store_pick_up"

Filter orders by delivery method.

  • shipment - Shipment
  • store_pick_up - Store pick-up
fulfilled_at_from
string <date-time>

Filter orders fulfilled from this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T00:00:00Z). If the time component is omitted, 00:00:00 is assumed.

fulfilled_at_to
string <date-time>

Filter orders fulfilled up to this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T23:59:59Z). If the time component is omitted, 23:59:59 is assumed.

fulfillment_status
string (Delivery Status)
Enum: "fulfilled" "partially_fulfilled" "unfulfilled"

Filter orders by fulfillment status.

  • unfulfilled - unfulfilled
  • partially_fulfilled - partially_fulfilled
  • fulfilled - fulfilled
is_canceled
boolean

Filter orders by cancellation status. Set to true to get canceled orders, false to get non-canceled orders.

order_ids
Array of integers

Filter orders by a comma-separated list of order IDs. Exact match on order.id. Max 200 IDs.

page
integer

A page number within the paginated result set.

paid_at_from
string <date-time>

Filter orders paid from this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T00:00:00Z). If the time component is omitted, 00:00:00 is assumed.

paid_at_to
string <date-time>

Filter orders paid up to this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T23:59:59Z). If the time component is omitted, 23:59:59 is assumed.

payment_status
string
Enum: "paid" "unpaid"

Filter orders by payment status.

  • paid - Paid
  • unpaid - Unpaid
per_page
integer <= 100
Default: 50

Number of results to return per page.

sort
string

Which field to use when ordering the results. Use '_asc' or '_desc' suffix to specify ascending or descending order. Valid values are: created_at_asc, created_at_desc, id_asc, id_desc, updated_at_asc, updated_at_desc, paid_at_asc, paid_at_desc, fulfilled_at_asc, fulfilled_at_desc.

Default value: created_at_desc

warehouse_release_status
string (State in the warehouse)
Enum: "not_released" "partially_released" "released"

Filter orders by warehouse release status.

  • not_released - not_released
  • partially_released - partially_released
  • released - released

Responses

Response samples

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

Get Order Detail

Retrieve detailed information about a specific order by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
Example
{
  • "id": 1267,
  • "payment_status": "paid",
  • "warehouse_release_status": "released",
  • "fulfillment_status": "fulfilled",
  • "created_at": "2026-03-18T10:15:22Z",
  • "paid_at": "2026-03-18T10:20:00Z",
  • "fulfilled_at": "2026-03-19T15:00:00Z",
  • "canceled_at": null,
  • "delivery_method": "shipment",
  • "locale": "es-ES",
  • "payment_method": "card",
  • "payment_gateway": "stripe",
  • "total": {
    },
  • "shipping": {
    },
  • "fees": {
    },
  • "email": "john.smith@example.com"
}

Price Lists

A Price List defines customer-specific prices, discounts and purchase conditions for products. Price lists can include: fixed prices for variants, percentage discounts, quantity-based pricing rules and minimum order requirements.

Important considerations:

  • Custom price lists are typically used in B2B scenarios.
  • Customers assigned to a price list see adjusted pricing across the storefront and checkout.
  • If multiple price lists apply to the same customer, the final pricing is resolved automatically using the most specific applicable rule. When multiple rules with the same specificity apply, the best price for the customer is used.

    Pricing priority:

    • Fixed prices (lowest price wins)
    • Brand discounts (highest discount wins)
    • Category discounts (most specific category, then highest discount)
    • Global discounts (highest discount wins)

    If a product belongs to multiple categories, the main product category is used for category discount calculation.

  • Products without applicable price list rules continue using their default storefront pricing.
  • Customers with a custom price list assigned are not eligible for standard promotions, automatic discounts, promotional codes, flash offers or regular quantity discounts and cannot add additional services to the cart.

Fixed fields: id

Default fields: internal_id, is_active, minimum_order_amount, customers_count, variant_prices_count, global_discount

See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Price Lists

Retrieve a paginated list of price lists with optional filtering.

Authorizations:
ApiKeyAuth
query Parameters
internal_ids
Array of strings

Filter price lists by a comma-separated list of price list internal IDs. Exact match on price_list.internal_id. Max 200 IDs.

is_active
boolean

Filter price lists by active status.

page
integer

A page number within the paginated result set.

per_page
integer <= 100
Default: 50

Number of results to return per page.

price_list_ids
Array of integers

Filter price lists by a comma-separated list of price list IDs. Exact match on price_list.id. Max 200 IDs.

Responses

Response samples

Content type
application/json
{}

Create Price List

Creates a new price list.
This endpoint only creates the price list configuration. Fixed prices by product must be managed separately.

Authorizations:
ApiKeyAuth
Request Body schema:
required
internal_id
required
string <= 100 characters

Merchant-defined identifier used to manage the price list through imports, exports and the API.

is_active
required
boolean

Indicates whether the price list is active.

object (Money)

Minimum order amount required for customers using this custom price list.

global_discount
required
string <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$

Global discount percentage applied by the custom price list when applicable. Expressed as a percentage value.

required
Array of objects (CategoriesPriceList)

List of category discount rules configured in this custom price list. Each rule applies the specified discount percentage to all included categories.

required
Array of objects (BrandsPriceList)

List of brand discount rules configured in this custom price list. Each rule applies the specified discount percentage to all included brands.

Responses

Request samples

Content type
{
  • "internal_id": "distributor-ESP",
  • "is_active": true,
  • "minimum_order_amount": {
    },
  • "global_discount": "10.00",
  • "category_discounts": [
    ],
  • "brand_discounts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 3,
  • "internal_id": "distributor-ESP",
  • "is_active": true,
  • "minimum_order_amount": {
    },
  • "customers_count": 74,
  • "variant_prices_count": 1942,
  • "global_discount": "10.00",
  • "category_discounts": [],
  • "brand_discounts": []
}

Get Price List Detail

Returns a single price list.
This endpoint does not return fixed prices by variant.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 3,
  • "internal_id": "distributor-ESP",
  • "is_active": true,
  • "minimum_order_amount": null,
  • "customers_count": 74,
  • "variant_prices_count": 1942,
  • "global_discount": "10.00",
  • "category_discounts": [],
  • "brand_discounts": []
}

Update Price List

Updates an existing price list.
This endpoint only updates the price list configuration. It does not create, update or delete fixed prices by product.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer
Request Body schema:
internal_id
string <= 100 characters

Merchant-defined identifier used to manage the price list through imports, exports and the API.

is_active
boolean

Indicates whether the price list is active.

object (Money)

Minimum order amount required for customers using this custom price list.

global_discount
string <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$

Global discount percentage applied by the custom price list when applicable. Expressed as a percentage value.

Array of objects (CategoriesPriceList)

List of category discount rules configured in this custom price list. Each rule applies the specified discount percentage to all included categories.

Array of objects (BrandsPriceList)

List of brand discount rules configured in this custom price list. Each rule applies the specified discount percentage to all included brands.

Responses

Request samples

Content type
{
  • "internal_id": "distributor-ESP",
  • "is_active": true,
  • "minimum_order_amount": {
    },
  • "global_discount": "10.00",
  • "category_discounts": [
    ],
  • "brand_discounts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 3,
  • "internal_id": "distributor-ESP",
  • "is_active": true,
  • "minimum_order_amount": {
    },
  • "customers_count": 74,
  • "variant_prices_count": 1942,
  • "global_discount": "10.00",
  • "category_discounts": [],
  • "brand_discounts": []
}

Delete Price List

Deletes a price list and all associated data, including fixed prices by product.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

List Variant Prices

Retrieve a paginated list of variant prices configured for a specific price list, with optional filtering and ordering. Use this endpoint to inspect fixed prices, minimum quantities and quantity multiples applied by the price list to specific variants.

This endpoint returns customer-specific variant prices configured in the selected price list. It does not return the standard catalog prices configured for variants.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer
query Parameters
ean
Array of strings

Filter price list variant prices by a comma-separated list of EAN/UPC codes. Max 200 EANs.

page
integer

A page number within the paginated result set.

per_page
integer <= 500
Default: 100

Number of results to return per page.

product_ids
Array of integers

Filter price list variant prices by a comma-separated list of product IDs. Max 200 IDs.

product_internal_ids
Array of strings

Filter price list variant prices by a comma-separated list of product internal IDs. Max 200 IDs.

sku
Array of strings

Filter price list variant prices by a comma-separated list of SKUs. Max 200 SKUs.

sort
string

Which field to use when ordering the results. Use '_asc' or '_desc' suffix to specify ascending or descending order. Valid values are: variant_id_asc, variant_id_desc, variant_internal_id_asc, variant_internal_id_desc, product_id_asc, product_id_desc, product_internal_id_asc, product_internal_id_desc, ean_asc, ean_desc, sku_asc, sku_desc, supplier_id_asc, supplier_id_desc, supplier_internal_id_asc, supplier_internal_id_desc.

Default value: variant_id_asc

supplier_id
integer

Filter price list variant prices by variant's product supplier ID.

supplier_internal_id
Array of strings

Filter price list variant prices by variant's product supplier internal ID.

variant_ids
Array of integers

Filter price list variant prices by a comma-separated list of variant IDs. Max 200 IDs.

variant_internal_ids
Array of strings

Filter price list variant prices by a comma-separated list of variant internal IDs. Max 200 IDs.

Responses

Response samples

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

Delete Variant Prices

Deletes all variant prices configured in the price list.

This operation removes every fixed price by variant from the price list, including any variant-level minimum quantity and quantity multiple values.

This endpoint does not delete the price list itself, nor does it modify price list configuration fields such as global discounts, category discounts, brand discounts, active state or minimum order amount.

After deletion, variants affected by this price list no longer have fixed prices from this price list. They may still be affected by other price list rules, such as brand, category or global discounts.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Bulk Update Variant Prices

Creates an asynchronous bulk update job to manage variant prices within a price list.

Use this endpoint to process variant prices in bulk. The operation to perform is defined by options.mode:

  • upsert: creates new variant prices and updates existing ones. Existing prices that are not included in the payload remain unchanged.
  • delete: removes the provided variant prices from the price list.

Variants can be matched using one of the supported identifiers defined by options.match_by: variant_id, variant_internal_id, ean or sku_supplier.

This endpoint only manages customer-specific variant prices configured within a price list. Price list configuration fields such as global discounts, category discounts, brand discounts, active state and minimum order amount are managed through the price list CRUD endpoints.

Asynchronous processing

This endpoint does not process the update within the request cycle. Before creating the job, OpenTiendas performs an initial validation of the request, including JSON format, payload structure, payload size and required top-level fields.

If the request fails this initial validation, no job is created and an error response is returned. The response may be 413 Request Entity Too Large if the payload exceeds the maximum allowed size, or 400 Bad Request for other validation errors.

If the request passes this initial validation, the endpoint creates and queues a job, then returns 202 Accepted with the corresponding job_id. This confirms that the request has been accepted for asynchronous processing, but does not mean that all reference prices have already been updated successfully.

Record-level validations and update operations are performed later, during job processing.

Job result

The progress and result of the operation can be reviewed using the returned job_id.

The job log includes processing information, validation errors, affected variant identifiers when available, and a final summary with the total processed and failed records.

Limits

Maximum request payload: 10 MB. Requests exceeding this limit are rejected.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer
Request Body schema:
required
required
Array of objects (PriceListVariantPriceUpdate)

Array of reference prices to process. The array cannot be empty. Each object must include the field used for matching, as defined by options.match_by.

required
object

Options for the bulk update operation.

Responses

Request samples

Content type
Example
{
  • "prices": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Products

A Product is a catalog container that groups one or more variants under a single listing (name, description, brand, categories, etc.). Products always have at least one variant. Pricing, inventory, and other operational data are managed at the variant level.

The product_structure field indicates whether the product supports multiple variants (with_variants) or is a single-variant product (simple).

Fixed fields: id

Default fields: internal_id, product_structure, status, product_kind, model_code, tax_category, images, variants_count, url, name, slug, slug_base

Nested objects: supplier, brand, categories, variants

No nested objects are included by default. Use the includes query parameter to include nested objects in the response.
See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Products

Retrieve a paginated list of products with optional filtering and ordering.

Authorizations:
ApiKeyAuth
query Parameters
brand_ids
Array of numbers

Filter products whose brand_id is in the comma-separated list of brand IDs. Max 50 IDs.

category_ids
Array of integers

Filter products by a comma-separated list of category IDs. Max 50 IDs.

Descendant categories are included. For example, filtering by the Clothes category returns all products assigned to that category and any of its subcategories (e.g. Trousers and Shirts).

created_at_from
string <date-time>

Filter products created from the given date and time. Uses product.created_at.

created_at_to
string <date-time>

Filter products created up to the given date and time. Uses product.created_at.

ean
Array of strings

Filter products by a comma-separated list of EAN/UPC codes. Max 200 EANs.

Exact match on variant.ean. Returns the parent product. When ean is present, variants is trimmed to only the variant(s) that match the ean filter.

internal_ids
Array of strings

Filter products by a comma-separated list of product internal IDs. Exact match on product.internal_id. Max 200 IDs.

page
integer

A page number within the paginated result set.

per_page
integer <= 100
Default: 50

Number of results to return per page.

product_ids
Array of integers

Filter products by a comma-separated list of product IDs. Exact match on product.id. Max 200 IDs.

product_structure
string
Enum: "simple" "with-variants"

Filter products by product structure.

  • simple - simple
  • with-variants - with-variants
sku
Array of strings

Filter products by a comma-separated list of SKUs. Max 200 SKUs.

Exact match case-insensitive on variant.sku (does not search product fields). Returns the parent product. When sku is present, variants is trimmed to only the variant(s) that match the sku filter.

slug
string

Filter products by a comma-separated list of slugs. Max 200 slugs.

sort
string

Which field to use when ordering the results. Use '_asc' or '_desc' suffix to specify ascending or descending order. Valid values are: name_asc, name_desc.

Default value: name_asc

status
string
Enum: "published" "unpublished"

Filter products by publication status.

  • published - published
  • unpublished - unpublished
supplier_ids
Array of numbers

Filter products that have at least one supplier in the comma-separated list of supplier IDs. Max 50 IDs.

updated_at_from
string <date-time>

Filter products updated on or after the given date and time. Uses product.updated_at.

Useful for incremental synchronization and change tracking.

This filter is intended to help detect products that may need to be re-synchronized, but should not be treated as a complete change history.

updated_at_to
string <date-time>

Filter products updated on or before the given date and time. Uses product.updated_at.

Useful for incremental synchronization and change tracking.

This filter is intended to help detect products that may need to be re-synchronized, but should not be treated as a complete change history.

Responses

Response samples

Content type
application/json
Example
{}

Get Product Detail

Retrieve detailed information about a specific product by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
Example
{}

Bulk Upsert Products

Creates an asynchronous bulk upsert job to create or updateproducts and their related data from the provided payload.

Asynchronous processing

This endpoint does not process the update within the request cycle. Before creating the job, OpenTiendas performs an initial validation of the request, including JSON format, payload structure, payload size and required top-level fields.

If the request fails this initial validation, no job is created and an error response is returned. The response may be 413 Request Entity Too Large if the payload exceeds the maximum allowed size, or 400 Bad Request for other validation errors.

If the request passes this initial validation, the endpoint creates and queues a job, then returns 202 Accepted with the corresponding job_id. This confirms that the request has been accepted for asynchronous processing, but does not mean that all variants have already been updated successfully.

Record-level validations and update operations are performed later, during job processing.

Job result

The progress and result of the operation can be reviewed using the returned job_id.

The job log includes processing information, validation errors, affected variant identifiers when available, and a final summary with the total processed and failed records.

Updating existing variants

When updating existing variants, it is not necessary to send the full variant data. The request only needs to include the identifier required by match_by and the fields that should be modified.

Supported match_by values are id and internal_id. id matches records using the OpenTiendas platform identifier. internal_id matches records using the custom internal identifier provided in the payload.

Limits

Maximum request payload: 10 MB. Requests exceeding this limit are rejected.

Authorizations:
ApiKeyAuth
Request Body schema:
required
required
Array of objects (ProductWrite)

List of products to create or update. Each product must include the field used for matching, as defined by options.match_by:

  • If match_by is id, existing products are matched by id.
  • If match_by is internal_id, existing products are matched by internal_id.
  • If no existing product is found, a new product is created.
required
object

Options for bulk upsert operation. Must include the 'match_by' field to specify how products should be matched for updates.

Responses

Request samples

Content type
{
  • "products": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Reviews

A Review represents customer feedback about a product (optionally a specific variant) or about the store. Reviews can be published/unpublished and include rating, content, author and other information.

Fixed fields: id

Default fields: locale, status, rating, created_at, type

See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Reviews

Retrieve a paginated list of reviews with optional filtering and ordering.

Authorizations:
ApiKeyAuth
query Parameters
created_at_from
string <date-time>

Filter reviews created from this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T00:00:00Z). If the time component is omitted, 00:00:00 is assumed.

created_at_to
string <date-time>

Filter reviews created up to this date/time (inclusive) in ISO 8601 format (e.g. 2023-01-01T23:59:59Z). If the time component is omitted, 23:59:59 is assumed.

locale
string
Enum: "ca-ES" "da-DK" "de-DE" "el-GR" "en-GB" "es-ES" "fr-FR" "hr-HR" "it-IT" "nl-NL" "pl-PL" "pt-PT" "ru-RU" "sv-SE"

Filter by locale.

  • es-ES - Spanish (Spain)
  • ca-ES - Catalan (Spain)
  • en-GB - English (United Kingdom)
  • fr-FR - French (France)
  • it-IT - Italian (Italy)
  • pt-PT - Portuguese (Portugal)
  • de-DE - German (Germany)
  • ru-RU - Russian (Russia)
  • nl-NL - Dutch (Netherlands)
  • sv-SE - Swedish (Sweden)
  • da-DK - Danish (Denmark)
  • pl-PL - Polish (Poland)
  • el-GR - Greek (Greece)
  • hr-HR - Croatian (Croatia)
page
integer

A page number within the paginated result set.

per_page
integer <= 100
Default: 50

Number of results to return per page.

product_id
number

Filter reviews by product ID.

rating
Array of integers

Filter reviews by a rating or a list of ratings (comma-separated). Valid rating values are 1 to 5.

sort
string

Which field to use when ordering the results. Use '_asc' or '_desc' suffix to specify ascending or descending order. Valid values are: created_at_asc, created_at_desc, rating_asc, rating_desc.

Default value: created_at_desc

status
string
Enum: "published" "unpublished"

Filter reviews by publication status.

  • published - published
  • unpublished - unpublished
type
string or null
Enum: null "product" "store"

Filter reviews by type.

Responses

Response samples

Content type
application/json
Example
{}

Create Review

Create a new review with the provided details.

Authorizations:
ApiKeyAuth
Request Body schema:
required
locale
required
string
Enum: "es-ES" "ca-ES" "en-GB" "fr-FR" "it-IT" "pt-PT" "de-DE" "ru-RU" "nl-NL" "sv-SE" "da-DK" "pl-PL" "el-GR" "hr-HR"

Locale code in ISO format (e.g., es-ES, en-GB).Format follows ISO 639-1 (language) and ISO 3166-1 alpha-2 (country) standards.

  • es-ES - Spanish (Spain)
  • ca-ES - Catalan (Spain)
  • en-GB - English (United Kingdom)
  • fr-FR - French (France)
  • it-IT - Italian (Italy)
  • pt-PT - Portuguese (Portugal)
  • de-DE - German (Germany)
  • ru-RU - Russian (Russia)
  • nl-NL - Dutch (Netherlands)
  • sv-SE - Swedish (Sweden)
  • da-DK - Danish (Denmark)
  • pl-PL - Polish (Poland)
  • el-GR - Greek (Greece)
  • hr-HR - Croatian (Croatia)
status
string
Enum: "published" "unpublished"

Status of the object: 'published' or 'unpublished'.

  • published - published
  • unpublished - unpublished
rating
integer [ 1 .. 5 ]

Rating from 1 (minimum) to 5 (maximum).

content
required
string

Content of the review.

created_at
string <date-time>

Date and time in ISO 8601 format (e.g., 2023-10-01T12:00:00Z). Microseconds are not included.

reviewer_name
string

Name of the reviewer.

reviewer_email
required
string <email>

Email of the reviewer.

order_id
integer or null (Order number)

ID of the order associated with the review, if applicable. If a review is associated with an order, it will be considered a verified review. This verification helps build trust and transparency for shoppers browsing your store.

customer_id
integer or null

ID of the customer (contact) who wrote the review.

type
required
string
Enum: "product" "store"

Type of review: 'product' for product reviews, 'store' for store reviews.

  • product - product
  • store - store
product_id
integer or null

ID of the product being reviewed. Only for 'product' reviews.

variant_id
integer or null

ID of the variant being reviewed. Only for 'product' reviews.

Responses

Request samples

Content type
{
  • "locale": "en-GB",
  • "status": "published",
  • "rating": 5,
  • "content": "The product matches the description perfectly. Highly recommended.",
  • "created_at": "2024-01-15T09:22:10Z",
  • "reviewer_name": "Emily Smith",
  • "reviewer_email": "emily.smith@example.com",
  • "order_id": 123456,
  • "customer_id": 789,
  • "type": "product",
  • "product_id": 2532,
  • "variant_id": null
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Review Detail

Retrieve detailed information about a specific review by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
Example
{
  • "id": 3,
  • "locale": "en-GB",
  • "status": "published",
  • "rating": 5,
  • "created_at": "2024-01-15T09:22:10Z",
  • "type": "store"
}

Update Review

Update an existing review's details.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer
Request Body schema:
locale
string
Enum: "es-ES" "ca-ES" "en-GB" "fr-FR" "it-IT" "pt-PT" "de-DE" "ru-RU" "nl-NL" "sv-SE" "da-DK" "pl-PL" "el-GR" "hr-HR"

Locale code in ISO format (e.g., es-ES, en-GB).Format follows ISO 639-1 (language) and ISO 3166-1 alpha-2 (country) standards.

  • es-ES - Spanish (Spain)
  • ca-ES - Catalan (Spain)
  • en-GB - English (United Kingdom)
  • fr-FR - French (France)
  • it-IT - Italian (Italy)
  • pt-PT - Portuguese (Portugal)
  • de-DE - German (Germany)
  • ru-RU - Russian (Russia)
  • nl-NL - Dutch (Netherlands)
  • sv-SE - Swedish (Sweden)
  • da-DK - Danish (Denmark)
  • pl-PL - Polish (Poland)
  • el-GR - Greek (Greece)
  • hr-HR - Croatian (Croatia)
status
string
Enum: "published" "unpublished"

Status of the object: 'published' or 'unpublished'.

  • published - published
  • unpublished - unpublished
rating
integer [ 1 .. 5 ]

Rating from 1 (minimum) to 5 (maximum).

content
string

Content of the review.

created_at
string <date-time>

Date and time in ISO 8601 format (e.g., 2023-10-01T12:00:00Z). Microseconds are not included.

reviewer_name
string

Name of the reviewer.

reviewer_email
string <email>

Email of the reviewer.

order_id
integer or null (Order number)

ID of the order associated with the review, if applicable. If a review is associated with an order, it will be considered a verified review. This verification helps build trust and transparency for shoppers browsing your store.

customer_id
integer or null

ID of the customer (contact) who wrote the review.

type
string
Enum: "product" "store"

Type of review: 'product' for product reviews, 'store' for store reviews.

  • product - product
  • store - store
product_id
integer or null

ID of the product being reviewed. Only for 'product' reviews.

variant_id
integer or null

ID of the variant being reviewed. Only for 'product' reviews.

Responses

Request samples

Content type
{
  • "content": "The shopping experience was good.",
  • "rating": 4
}

Response samples

Content type
application/json
{
  • "id": 3,
  • "locale": "en-GB",
  • "status": "published",
  • "rating": 4,
  • "created_at": "2024-01-15T09:22:10Z",
  • "type": "store"
}

Delete Review

Delete a specific review by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Store

The Store resource represents the global configuration and public identity of the shop. It exposes high-level information such as the store name or domains.

Get Store Information

Retrieves the store's return policy, and the name, domain, logo URL, and configured email accounts for each supported locale.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "return_policy": {
    },
  • "translations": {
    }
}

Suppliers

A Supplier represents a company or entity that provides products to the store. Suppliers are used internally for stock sourcing, logistics, purchasing workflows, and reporting. Supplier data is not localized and is intended for back-office and integration use.

Fixed fields: name

Default fields: id

See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Suppliers

Retrieve a paginated list of suppliers.

Authorizations:
ApiKeyAuth
query Parameters
page
integer

A page number within the paginated result set.

per_page
integer <= 100
Default: 50

Number of results to return per page.

Responses

Response samples

Content type
application/json
Example
{}

Create Supplier

Create a new supplier with the provided details.

Authorizations:
ApiKeyAuth
Request Body schema:
required
name
required
string

Name of the supplier.

internal_id
required
string

Internal ID for the supplier. This alternative identifier is intended for linking it with external systems and managing it through imports or API integrations.

description
string

Internal description of the supplier.

Responses

Request samples

Content type
{
  • "name": "New Supplier",
  • "internal_id": "SUP-002",
  • "description": "A newly created supplier"
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "name": "New Supplier"
}

Get Supplier Detail

Retrieve detailed information about a specific supplier by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "name": "Supplier A"
}

Update Supplier

Update an existing supplier's details.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer
Request Body schema:
name
string

Name of the supplier.

internal_id
string

Internal ID for the supplier. This alternative identifier is intended for linking it with external systems and managing it through imports or API integrations.

description
string

Internal description of the supplier.

Responses

Request samples

Content type
{
  • "description": "Updated description for Supplier A."
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Supplier A"
}

Delete Supplier

Delete a specific supplier by its ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

Responses

Variants

A Variant represents a purchasable SKU of a product (the exact item a customer buys, e.g. "T-shirt / Black / M"). Every variant belongs to a parent product. Pricing, inventory, and other operational data are managed at the variant level.

Fixed fields: id

Default fields: internal_id, sku, ean, status, available_stock, name, selling_price

See the Field selection and response shape page for the global rules governing field selection and related resource inclusion.

List Variants of a Product

Retrieve a paginated list of variants of a product.

Authorizations:
ApiKeyAuth
path Parameters
product_id
required
integer
query Parameters
page
integer

A page number within the paginated result set.

per_page
integer <= 100
Default: 50

Number of results to return per page.

Responses

Response samples

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

Bulk Update Variants

Creates an asynchronous bulk update job to update variants and their related data from the provided payload.

Asynchronous processing

This endpoint does not process the update within the request cycle. Before creating the job, OpenTiendas performs an initial validation of the request, including JSON format, payload structure, payload size and required top-level fields.

If the request fails this initial validation, no job is created and an error response is returned. The response may be 413 Request Entity Too Large if the payload exceeds the maximum allowed size, or 400 Bad Request for other validation errors.

If the request passes this initial validation, the endpoint creates and queues a job, then returns 202 Accepted with the corresponding job_id. This confirms that the request has been accepted for asynchronous processing, but does not mean that all variants have already been updated successfully.

Record-level validations and update operations are performed later, during job processing.

Job result

The progress and result of the operation can be reviewed using the returned job_id.

The job log includes processing information, validation errors, affected variant identifiers when available, and a final summary with the total processed and failed records.

After the job is completed/finished, changes may take a short time to propagate across all parts of the shop.

Updating existing variants

When updating existing variants, it is not necessary to send the full variant data. The request only needs to include the identifier required by match_by and the fields that should be modified.

Supported match_by values are id, internal_id, ean, and sku_supplier. When using sku_supplier, the request must include both the SKU and the supplier internal ID.

Fields marked as required in this schema apply to variant creation.

Limits

Maximum request payload: 10 MB. Requests exceeding this limit are rejected.

Authorizations:
ApiKeyAuth
Request Body schema:
required
required
Array of objects (Variant)

List of variants to update. Each variant must include the field used for matching, as defined by options.match_by:

  • If match_by is id, existing variants are matched by id.
  • If match_by is internal_id, existing variants are matched by internal_id.
  • If match_by is ean, existing variants are matched by EAN.
  • If match_by is sku_supplier, existing variants are matched by the combination of SKU and supplier internal ID.
  • Only existing variants will be updated. New variants cannot be created through this endpoint.
required
object

Options for bulk update operation. Must include the 'match_by' field to specify how variants should be matched for updates.

Responses

Request samples

Content type
{
  • "variants": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]