Skip to content
platform
EN PT

API reference · Contracts · Head Office Management

Create Branch Contract

Method
POST
Route
/priceContract/store/:partnerId
Base URL
https://ws.autorei.net
Path parameters
:partnerId
Token
Requires Bearer token
Test in Postman

Opens this request in the public API documentation, the official source of the reference.

Description

Allows a head office account to create a price contract in one of its branches. Creation saves the contract header — validity period, scope and application filters. Customers and products are added afterward, through Add Customers to Branch Contract and Add Products to Branch Contract.

The body and the response are identical to those of creation in your own store — the difference is the branch that owns the contract, which comes in the route and is validated against your head office's links.

Path parameters

Parameter Type Required Description
partnerId integer Yes Id of the branch that owns the contract. Must be linked to the head office on the token.

Request body (JSON)

Field Type Required Description
name string Yes Contract name.
startDate datetime Yes Start of the validity period. See Accepted date formats.
endDate datetime Yes End of the validity period. Must be equal to or later than startDate.
allCustomers boolean Yes true applies the contract to all customers of the branch. See Customer scope.
allPartners boolean Yes true applies the contract to all branches of the head office. With true, partners is ignored.
active boolean No Active contract. Default true. Only an active contract within its validity period enters the price calculation.
priority integer No Priority when contracts compete. Default 0. See Which contract wins.
contractType string No BASIC (default) or COUNTDOWN. See Countdown offer.
priceBeforeAfter boolean No true returns the product's list price as the previous price, for the "from/to" display. See Countdown offer.
isDiscountBlockedByAttendant boolean No true prevents the attendant from giving a discount on the contract price in the cart.
stateList array No Abbreviations of the states (UFs) where the contract is valid, with two uppercase letters: ["SP","MG"]. Without the list, the contract is valid in any state.
storeList array No Ids of the stores where the contract is valid. Without the list, it is valid in any store.
partners array No Ids of the branches where the contract is valid. Ignored when allPartners is true.
customerGroupList array No Customer groups (price types) that the contract covers.
customerGroupList[].externalId string Yes Group id in your system, resolved to the platform id.

Accepted date formats

startDate and endDate accept four formats: 2026-09-01, 2026-09-01 08:30, 2026-09-01T08:30:00 and 2026-09-01T08:30:00Z. If only the date is sent, the validity period starts and ends at midnight.

Business rules

Customer scope

allCustomers: true applies the contract to all customers of the store, and the contract then rejects the addition of an individual customer with 400. With allCustomers: false, the contract is valid only for the customers you add afterward, one by one.

Which contract wins

When more than one active contract covers the same product for the same customer, the one with the highest priority wins. If priority is tied, the contract restricted to specific customers wins over the one that applies to all customers. If the tie persists, the oldest contract wins.

Countdown offer

contractType: COUNTDOWN marks the contract as a countdown offer: the returned price then carries the discount and the end date of the offer. The countdown contract only enters the price calculation with priceBeforeAfter: true.

Response · 200

Field Description
id Id of the contract created. It is the one used in the route of the contract's other endpoints.
name Saved name.
active Active contract.
partner.id Id of the partner that owns the contract.
partner.name · partner.document Name and document of the partner that owns the contract.
allCustomers · allPartners Saved scope.
priority Saved priority.
dateStart · dateEnd Saved validity period, in UTC.
dateCreated · lastUpdated Creation and last change, in UTC.
priceBeforeAfter Previous price enabled. Comes as null when you do not send the field.
contractType Saved type.
isDiscountBlockedByAttendant Saved discount block.
priceContractPartners Ids of the branches saved from partners.
priceContractStates States (UFs) saved from stateList.
priceContractCustomerGroups Ids of the customer groups saved from customerGroupList.
priceContractStores Ids of the stores saved from storeList.

Errors

Code When
400 partnerId in the route is not numeric: {"error":"Invalid target partner ID"}.
400 The body is not valid JSON. The detail comes in error.
422 Empty body, missing required field (name, startDate, endDate, allCustomers, allPartners), date in an unaccepted format or endDate earlier than startDate. The detail comes in error.
401 Token missing, malformed or expired: {"error":"Authentication required for this route"}.
403 The branch is not linked to your head office: {"error":"Access denied: Invalid partnership"}. Unlike 400, here the payload is correct — what is missing is the link.

Example request

curl --request POST 'https://ws.autorei.net/priceContract/store/:partnerId' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Tabela Atacado Filial 2026",
  "startDate": "2026-09-01",
  "endDate": "2026-12-31",
  "allCustomers": false,
  "allPartners": false,
  "active": true,
  "priority": 10,
  "contractType": "BASIC",
  "isDiscountBlockedByAttendant": false,
  "stateList": [
    "SP",
    "MG"
  ],
  "customerGroupList": [
    {
      "externalId": "GRUPO-ATACADO"
    }
  ]
}'

Example responses

200Success — contract created

{
  "id": 4610002,
  "name": "Tabela Atacado Filial 2026",
  "active": true,
  "partner": {
    "id": 5057,
    "name": "Loja Exemplo - Filial Campinas",
    "document": "30.424.972/0002-55"
  },
  "allCustomers": false,
  "allPartners": false,
  "priority": 10,
  "dateStart": "2026-09-01T00:00:00Z",
  "dateEnd": "2026-12-31T00:00:00Z",
  "dateCreated": "2026-09-04T13:22:32.687284Z",
  "lastUpdated": "2026-09-04T13:22:32.687284Z",
  "priceBeforeAfter": null,
  "contractType": "BASIC",
  "isDiscountBlockedByAttendant": false,
  "priceContractPartners": [],
  "priceContractStates": [
    "SP",
    "MG"
  ],
  "priceContractCustomerGroups": [
    4610101
  ],
  "priceContractStores": []
}

Used in

Related endpoints

← See the group: Contracts

Generated from the public API collection, published on 2026-09-04: api-docs.cws.digital.