Marketplace
    • Getting an API token
    • Introduction
    • Customers
      • Get a list of Customer Fields
        GET
      • Retrieve Customer Fields matching the given ID
        GET
      • Get a list of Customers
        GET
      • Retrieve Customers matching the given ID
        GET
      • Update a Customer
        PUT
      • Delete a Customer
        DELETE
      • Bulk Add/Update Customers
        POST
      • Create a new Customer
        POST
      • Get a list of Orders
        GET
    • Distributors
      • Get a list of Distributors
        GET
      • Retrieve Distributors matching the given ID
        GET
      • Update a Distributor
        PUT
      • Delete a Distributor
        DELETE
      • Create a new Distributor
        POST
    • Warehouses
      • Get a list of Warehouses
        GET
      • Retrieve Warehouses matching the given ID
        GET
      • Update a Warehouse
        PUT
      • Delete a Warehouse
        DELETE
      • Bulk Add/Update Warehouses
        POST
      • Create a new Warehouse
        POST
    • Exports
      • Get available exports
        GET
      • Get parameter options
        GET
      • Run custom export
        POST
    • Orders
      • Get a list of Order Batches
      • Retrieve Order Batch matching the given order batch Ids (from orderBatches/list)
      • Update Order Batch status
      • Delete Order Batch
      • Create a new Order
      • Update an existing Order
      • Bulk Add/Update Orders
      • Bulk Update Order Batch Statuses
    • People
      • Get a list of People
      • Retrieve a specific Person by ID
      • Update a Person
      • Delete a Person
      • Create a new Person
      • Bulk Add/Update Persons
      • Get a list of roles
      • Get a list of person types
      • Retrieve a specific Person Type by ID
    • Products
      • Get a list of Products
      • Create a new Product
      • Bulk Add/Update Products
      • Retrieve Products matching the given ID
      • Update a Product
      • Delete a Product
      • Get a list of Product Skus
      • Create a new Product Sku
      • Update a Product Sku
      • Bulk Add/Update Product Skus
      • Get a list of Pricing information for a given product
      • Bulk Add/Update Pricing
      • Get a list of categories
      • Get a list of brands
      • Get a list of PriceZones
      • Get a list of Product Fields
      • Get a list of Product Sku Fields
      • Get a list of product options
      • Retrieve a product option matching the given ID
      • Update a product option
      • Delete a product option
      • Create a new product option
      • Update Pricing for a product that starts on a given date
      • Create new Pricing for a product
      • Delete Pricing for a product that starts on a given date
      • Retrieve a field matching the given ID
      • Add or update the component SKUs linked to a kit Product
      • Bulk Add/Update the component SKUs linked to kit Products, across any number of kits
    • Vendors
      • Get a list of Vendors
      • Retrieve Vendors matching the given ID
      • Update a Vendor
      • Delete a Vendor
      • Bulk Add/Update Vendors
      • Create a new Vendor
    • Content
    • Promotions
      • Get a list of Promotions
      • Retrieve the Promotion matching the given ID
      • Get a list of Deals linked to the given Promotion
      • Retrieve the Deal matching the given ID under the given Promotion
      • Update the Deal's details, and optionally its status. Card and banner appearance stays inherited from the Promotion
      • Bulk Add/Update fixed price Deals under the given Promotion
      • Set the Deal's fixed price reward, with a price per product
      • Add products to the Deal's fixed price reward pool
      • Set the Deal's warehouses, price zones, customers and delivery dates in one call
    • Imports
    • Product Skus
      • Retrieve Fields matching the given ID
      • Retrieve Product Skus matching the given ID
      • Delete a Product Sku
      • Bulk Add/Update Product Skus across multiple Products
    • Pricing
      • Retrieve Pricing for a product that starts on a given date
      • Bulk Add/Update Pricing across multiple products
    • PriceZones
      • Retrieve PriceZone by ID
    • Product Highlights
      • Get a list of product highlights
      • Add products to the product highlight with a name, creating it if there is none
      • Add products to a product highlight
    • Product Options
    • Schemas
      • Schemas
        • Export
        • ExportParameter
        • PriceAssociatedProductSku
        • PriceList
        • Pricing
      • BulkFailMessage
      • AddressApiInput
      • DealAvailability
      • BulkSkippedProduct
      • SelectionItem
      • ProductOption
      • Customer
      • Address
      • Country
      • State
      • Distributor
      • FreeStock
      • OrderBatch
      • OrderLine
      • Person
      • PersonType
      • PricingMutation
      • ProductSku
      • Vendor
      • Warehouse
      • WarehouseUnderDistributor
      • BulkUpdateResult
      • Deal
      • DealBulkItemApiInput
      • DealUpdateApiInput
      • FIELD_TYPE
      • PERMISSION
      • PriceListMutation
      • ProductSkuApiInput
      • SELECTION_TYPE
      • DealAvailabilityApiInput
      • BulkSuccessItem
      • DealBulkApiInput
      • CompleteOrder
      • DealDateRange
      • CompleteOrderApiInput
      • DealDeliveryDateRangeApiInput
      • CompleteOrderBulkApiInput
      • DealPagedResults
      • CompleteOrderQuantityApiInput
      • DealProductPrice
      • CompleteOrderWithIdApiInput
      • DealProductPriceApiInput
      • DealProductsApiInput
      • DealReward
      • CustomerApiInput
      • CustomerAssociation
      • ENTITY_STATUS
      • CustomerAssociationApiInput
      • EntityAssociationResult
      • CustomerBulkApiInput
      • FIELD_COMPONENT
      • CustomerOrdering
      • CustomerOrderingApiInput
      • CustomerRule
      • Field
      • CustomerRuleApiInput
      • FieldComponent
      • CustomersConnection
      • KitComponent
      • PagedResults
      • DistributorPagedResults
      • PriceZone
      • ENTITY_STATUS_WITH_TEST
      • PricingCrossProductBulkApiInput
      • Email
      • ProductKitComponentApiInput
      • Error
      • ProductKitComponentBulkApiInput
      • ProductKitComponentCrossProductBulkApiInput
      • ProductSkuCrossProductBulkApiInput
      • Promotion
      • PromotionPagedResults
      • REWARD_APPLY
      • RolePermission
      • ORDER_STATUS
      • Section
      • OrderBatchStatusApiInput
      • Selection
      • OrderBatchStatusBulkApiInput
      • VISIBILITY
      • OrdersConnection
      • PRODUCT_SKU_STATUS_RAW
      • PersonApiInput
      • PersonBulkApiInput
      • PersonRule
      • PersonRuleApiInput
      • PersonTypeAssociation
      • PersonTypeAssociationApiInput
      • PersonsConnection
      • Phone
      • PriceAssociatedProductSkuMutation
      • PriceZonePagedResults
      • PricingBulkApiInput
      • PricingPagedResults
      • Product
      • ProductApiInput
      • ProductAssociation
      • ProductAssociationApiInput
      • ProductBulkApiInput
      • ProductHighlight
      • ProductHighlightByNameApiInput
      • ProductHighlightByNameResult
      • ProductHighlightPagedResults
      • ProductHighlightProductsApiInput
      • ProductOptionApiInput
      • ProductPagedResults
      • ProductRule
      • ProductRuleApiInput
      • ProductSkuBulkApiInput
      • SelectionPagedResults
      • VALIDATION_STATUS
      • ValidationProblemDetails
      • VendorApiInput
      • VendorBulkApiInput
      • VendorBulkItemApiInput
      • VendorPagedResults
      • WarehouseApiInput
      • WarehouseBulkApiInput
      • WarehouseBulkDistributorApiInput
      • WarehouseBulkItemApiInput
      • WarehousePagedResults
      • WarehouseSkuId

    Introduction

    The Marketplace API lets your systems read and write your company's Marketplace data: products, SKUs, pricing, customers, people, promotions and deals, orders, and the records around them. This page covers what applies to every endpoint. Read it before the endpoint reference.

    Environments#

    The API's base URL is https://marketplacerest.perenso.net.
    A token works only in the company it was created in: a token from one company can't read or write another company's data. To build and test your integration without touching live data, ask Perenso for a test company.

    Authentication#

    Send your token on every request:
    Create tokens in the Admin portal; see Getting an API token.
    A token lasts 365 days. Create a new one and switch to it before the old one expires.
    A token can be deactivated or deleted in the Admin portal at any time, and is refused from the next request.
    A request with a missing, expired, deactivated or deleted token answers 401.

    IDs#

    A record's id is your id for it, such as your product code or customer number. You choose it when you create the record, and you use it in every route that names the record (GET v1/customers/{id}).
    References use the same ids: a product's vendorId, brandId and categoryId are the ids you gave the vendor, brand and category.
    Ids are matched ignoring case and trailing spaces.
    Bulk results also carry an entityId, which is Marketplace's own id for the record. You don't need it for anything in this API.

    Pagination#

    Most lists are paged by cursor and answer:
    {
      "items": [ ... ],
      "pagination": {
        "endCursor": "MQ==",
        "startCursor": "MA==",
        "hasNextPage": true,
        "hasPreviousPage": false,
        "totalRecords": 248,
        "resultsPerPage": 100
      }
    }
    resultsPerPage defaults to 100 and is at most 500; more answers 400.
    For the next page, send the previous page's endCursor as cursor. Keep going until hasNextPage is false.
    A few lists aren't paged and answer a plain array with every record: fields, roles, person types, product options and a product's SKUs. Each says so in the reference.
    The exports list pages by number instead: page starts at 1, and resultsPerPage defaults to 20.

    Errors and retries#

    StatusMeaningWhat to do
    400The request is wrong: a missing or badly formed value, or an id that names nothingFix the request. Sent unchanged, it fails again
    401The token is missing, expired, deactivated or deletedUse a valid token
    404The record in the route doesn't exist, or the route doesn'tCheck the id and the path
    429The token has made too many requestsWait Retry-After seconds, then retry
    500The request couldn't be completedRetry with backoff (see below)
    503The API is temporarily unavailableWait Retry-After seconds, then retry
    An error from the API itself carries Message, or Messages when there is more than one problem:
    { "Message": "priceZoneId not found" }
    { "Messages": ["Multiple errors occurred:", "- <first problem>", "- <second problem>"] }
    A body that doesn't match the endpoint's schema, such as a number where text belongs, is refused before it reaches the API, with this shape instead. errors names each field that couldn't be read:
    {
      "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
      "title": "One or more validation errors occurred.",
      "status": 400,
      "errors": {
        "$.name": ["The JSON value could not be converted to System.String. Path: $.name | LineNumber: 0 | BytePositionInLine: 11."]
      },
      "traceId": "00-ed02ce30cc3351f5f23d8a9b15df3259-4ab78800adf41880-00"
    }
    A 500 carries a CorrelationId. Quote it when you contact Perenso support:
    { "Message": "An error occurred. Please try again later.", "CorrelationId": "4bf92f3577b34da6a3ce929d0e0e4736" }
    Retrying a 500. Bulk calls create or update by id, so they are safe to send again. A single create (POST .../create) is not: if it answered 500 but did save, sending it again answers 400 because the id is taken. After a failed create, read the record by its id before you create it again. Orders have no id of yours, so give an order create an externalReference: sending it again answers the order the first call made instead of placing a second one.

    Bulk endpoints#

    Bulk endpoints (POST .../bulk) create or update many records in one call, matched by your id: a row whose id is new creates the record, and a row whose id exists updates it.
    {
      "successful": ["PROD-1042"],
      "successfulItems": [
        { "id": "PROD-1042", "entityId": "UHJvZHVjdENvcmUKaTEwNDI=", "created": false, "skippedProducts": null }
      ],
      "failed": [
        { "id": "PROD-1043", "message": "vendorId not found" }
      ]
    }
    Always read failed. Each row succeeds or fails on its own, so a call that answers 200 can still have rows that failed. A failed row names its id and the reason; fix it and send just that row again.
    A row without an id, or with the same id as an earlier row in the call, fails. Orders are the exception: a row without an id creates an order, and is named by its externalReference, or as "Row n" when it has none.
    created says whether a row created the record (true) or updated it (false). Only the products and orders routes report it; elsewhere it is null.
    Send at most 100 rows a call.

    Updates#

    A single update (PUT .../{id}) and a bulk row follow the same rules for each field:
    Leaving a field out, or sending null, keeps the stored value. Send only what you want to change.
    "" clears a text field, such as a phone number, email or notes, and [] clears a list.
    A reference id sent as "" keeps the stored value, as if you'd left it out: a product's vendorId, brandId, categoryId and weightUnitId, and a customer's gradeId, orderingGroupId and priceZoneId. Integration tools often send "" for an empty column, so these can't be cleared through the API.
    An update is addressed by the id in the route. A body without an id keeps it; a different id in the body changes the record's id. Product options are the exception: their id can't be changed.
    An update to a record that doesn't exist answers 404.
    Some records don't follow the first rule. Each is described on its endpoint:
    SKUs: a SKU write replaces the whole SKU, apart from its status. Send every field you want to keep.
    Deals: a bulk deal row replaces the deal's other fields. A deal's status is kept when it's left out.
    Orders: an order keeps any line the call leaves out. To remove a line, send it with "delete": true.
    Defaults that may surprise you:
    A SKU created without a status is IN_CATALOG: it is listed but can't be ordered. Send "status": "ACTIVE" to make it orderable.
    A product created without a status is ACTIVE.

    Query strings#

    Keep a query string under 2,000 characters after encoding. A longer one is refused with a bare 404 before it reaches the API, so it looks like a missing route.
    A parameter sent empty (?name=) is the same as leaving it out.

    Rate limits#

    Each token can make 300 requests a minute. The allowance refills continuously, one request every 0.2 seconds, so a token that has been idle can send 300 at once.
    Over the limit, a request answers 429 with a Retry-After header giving the seconds to wait, usually about one:
    { "Message": "Too many requests for this access token. Wait the number of seconds in the Retry-After header before trying again." }
    Wait that long, then retry. Each token has its own allowance.
    Modified at 2026-11-17 20:32:23
    Previous
    Getting an API token
    Next
    Get a list of Customer Fields
    Built with