Vendor API
Connect your integration to this storefront's inventory, customer records, and pickup orders.
Quickstart
- Base URL
https://my.showgrow.com/api/v1/
Ask a store administrator for a key with inventory:read access. Replace YOUR_API_KEY in the example to make your first request.
Keep the key on your server and use HTTPS in production. Download the OpenAPI specification.
curl 'https://my.showgrow.com/api/v1/locations' \
-H 'Authorization: Bearer YOUR_API_KEY'
Place a pickup order
- Pick a location and products. Call
GET /locationsand use its location ID withGET /inventory. - Get a customer ID. Create or reuse your integration's record through
POST /customers. - Build the cart. Use your own
cartIdto open a draft. Set product quantities with the latestversion. - Submit and track the order. Confirm the customer's eligibility, submit the cart, and store the
orderIdto check its status. Payment is handled at pickup.
Endpoint reference
Inventory
GET
/api/v1/locations
List storefront locations.
GET /api/v1/locations
Response locations contains the locations offered by this storefront.
GET
/api/v1/inventory
List sellable products and available quantities for a location.
| Field | Details |
|---|---|
locationIdQuery | Location ID from GET /locations. Required when the storefront has multiple locations. |
limitQuery | Page size. Defaults to 50. |
cursorQuery | Opaque nextCursor from the previous page. |
Reuse the same locationId for every page. Continue until nextCursor is null, even if a page is empty. Availability can change before checkout.
GET /api/v1/inventory?locationId=STORE_ID&limit=50
Response items includes productId, price, and availableQuantity. Prices are in USD. The cart recalculates prices and totals.
Carts
PUT
/api/v1/carts/{cartId}
Open a draft with your own stable cart reference.
| Field | Details |
|---|---|
cartIdPath | Your stable cart reference, up to 80 letters, numbers, hyphens, or underscores. |
locationIdJSON | Location ID from GET /locations. Required when the storefront has multiple locations. |
customerIdJSON | Customer ID issued to this integration. |
Retry with the same cart ID and create body to recover the existing cart. Drafts use version 0 and can expire under the storefront’s cart rules.
PUT /api/v1/carts/CART_ID
Content-Type: application/json
{
"locationId": "STORE_ID"
}
Response cart includes its cartId, version, status, totals in USD, and line IDs. A matching retry also returns replayed: true.
GET
/api/v1/carts/{cartId}
Read totals, line items, status, and the current version.
| Field | Details |
|---|---|
cartIdPath | Your stable cart reference, up to 80 letters, numbers, hyphens, or underscores. |
GET /api/v1/carts/CART_ID
Response cart includes its cartId, version, status, totals in USD, and line IDs. A matching retry also returns replayed: true.
PUT
/api/v1/carts/{cartId}/products/{productId}
Set the total quantity of a product in a draft.
| Field | Details |
|---|---|
cartIdPath | Your stable cart reference, up to 80 letters, numbers, hyphens, or underscores. |
productIdPath | Product ID from inventory. |
versionJSON · required | Version from the last cart response. |
quantityJSON · required | New total quantity for this product. |
Idempotency-KeyHeader · required | Unique key for this cart operation. Reuse it when retrying the same request. |
PUT /api/v1/carts/CART_ID/products/PRODUCT_ID
Idempotency-Key: vendor-request-123
Content-Type: application/json
{
"version": 0,
"quantity": 2
}
Response cart includes its cartId, version, status, totals in USD, and line IDs. A matching retry also returns replayed: true.
DELETE
/api/v1/carts/{cartId}/items/{lineId}
Remove a line from a draft by its line ID.
| Field | Details |
|---|---|
cartIdPath | Your stable cart reference, up to 80 letters, numbers, hyphens, or underscores. |
lineIdPath | Line ID from the cart response. |
versionQuery · required | Version from the last cart response. |
Idempotency-KeyHeader · required | Unique key for this cart operation. Reuse it when retrying the same request. |
DELETE /api/v1/carts/CART_ID/items/LINE_ID?version=1763496000000
Idempotency-Key: vendor-request-123
Response cart includes its cartId, version, status, totals in USD, and line IDs. A matching retry also returns replayed: true.
Orders
POST
/api/v1/carts/{cartId}/submit
Submit a pickup order from a draft.
| Field | Details |
|---|---|
cartIdPath | Your stable cart reference, up to 80 letters, numbers, hyphens, or underscores. |
versionJSON · required | Version from the last cart response. |
customerIdJSON | Customer ID issued to this integration. |
ageConfirmedJSON · required | Confirm that the customer is eligible to purchase. |
orderNotesJSON | Pickup notes. |
Idempotency-KeyHeader · required | Unique key for this cart operation. Reuse it when retrying the same request. |
Provide customerId if the cart has no customer. Submission checks current inventory and purchase limits. The customer pays at pickup.
POST /api/v1/carts/CART_ID/submit
Idempotency-Key: vendor-request-123
Content-Type: application/json
{
"version": 1763496000000,
"customerId": "CUSTOMER_ID",
"ageConfirmed": true
}
Response cart includes its cartId, version, status, totals in USD, and line IDs. A matching retry also returns replayed: true.
GET
/api/v1/orders/{orderId}
Track a submitted order by its stable order ID.
| Field | Details |
|---|---|
orderIdPath | Order ID returned at submission. |
Use the orderId returned at submission. The storefront owns fulfillment and cancellation.
GET /api/v1/orders/ORDER_ID
Response order includes the current storefront status, submission and update times, items, and totals in USD.
Customers
POST
/api/v1/customers
Create a customer for your integration.
| Field | Details |
|---|---|
phoneJSON · required | US phone number. |
firstNameJSON · required | First name. |
lastNameJSON | Last name. |
emailJSON | Email address. An empty string clears it. |
Retry with the same phone to recover a record created by this key. Existing records owned elsewhere return a conflict. Customer creation leaves marketing unsubscribed.
POST /api/v1/customers
Content-Type: application/json
{
"firstName": "Sam",
"lastName": "Rivera",
"phone": "2025550100"
}
Response customer includes its customerId, name, phone, and email where provided.
GET
/api/v1/customers/{customerId}
Read a customer created by this integration.
| Field | Details |
|---|---|
customerIdPath | Customer ID issued to this integration. |
GET /api/v1/customers/CUSTOMER_ID
Response customer includes its customerId, name, phone, and email where provided.
PATCH
/api/v1/customers/{customerId}
Update a customer’s name or email.
| Field | Details |
|---|---|
customerIdPath | Customer ID issued to this integration. |
firstNameJSON | First name. |
lastNameJSON | Last name. |
emailJSON | Email address. An empty string clears it. |
Supply at least one field. The phone number is fixed.
PATCH /api/v1/customers/CUSTOMER_ID
Content-Type: application/json
{
"firstName": "Samuel"
}
Response customer includes its customerId, name, phone, and email where provided.
Retries, limits, and access
Give every cart edit and submission a unique Idempotency-Key. If a response is lost, retry with the same key, path, and inputs. The API returns the current cart and replayed: true when it recognizes the request. The last 32 successful mutations are retained per cart. An older retry with a stale version receives a conflict.
For a version conflict, fetch the cart and reconcile the intended change. Use a new key when sending revised inputs. A new draft starts at version 0.
Each key has 120 requests per UTC minute. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and an X-RateLimit-Reset Unix timestamp in seconds.
Keys are scoped to one storefront and their own records. Rotating a secret preserves its records and permissions. Existing customer accounts cannot be looked up by phone through this API.
Error responses
Errors return error, code, and requestId. Include the request ID when contacting support.
| Status | What to check |
|---|---|
400 | Invalid request. Check the path, headers, and required fields. |
401 | Invalid key. Check the bearer key, its expiration, and the storefront that issued it. |
403 | Access denied. Check the key permission and storefront settings. |
404 | Resource unavailable. Check the path or resource ID. Carts, orders, and customers belong to the integration that created them. |
409 | Conflict. For CART_VERSION_CONFLICT, read the latest cart before retrying. For IDEMPOTENCY_CONFLICT, use a new idempotency key for a different operation. |
415 | Unsupported content type. Send JSON bodies as application/json. |
429 | Request limit reached. Wait for the number of seconds in Retry-After. |
503 | Service unavailable. Retry with backoff. Use the same idempotency key and body for cart mutations. |
Earlier API endpoints
These paths are available for existing integrations. Use the versioned endpoints for a new integration.
GET
/api/getInventory/List locations and in-stock products.
Required permission inventory:read
/api/getInventory/?locationId=STORE_ID&limit=50&offset=0
GET
/api/getCart/View a vendor cart and its current version.
Required permission cart:read
/api/getCart/?cartId=vendor-order-42
POST
/api/addToCart/Create a draft or add a quantity to an existing draft. Use version 0 on the first call.
Required permission cart:write
{
"cartId": "vendor-order-42",
"version": 0,
"locationId": "STORE_ID",
"productId": "PRODUCT_ID",
"quantity": 1
}
POST
/api/removeFromCart/Remove a cart line. Pass quantity to remove only part of the line.
Required permission cart:write
{
"cartId": "vendor-order-42",
"version": 1763496000000,
"lineId": "LINE_ID"
}
POST
/api/submitCart/Submit a pickup order. Repeating a successful submission returns the existing order.
Required permission cart:submit
{
"cartId": "vendor-order-42",
"version": 1763496000000,
"customerId": "CUSTOMER_ID",
"ageConfirmed": true
}
POST
/api/createCustomer/Create a customer record. A retry with the same phone and key returns that record.
Required permission customer:write
{
"firstName": "Sam",
"lastName": "Rivera",
"phone": "2025550100",
"email": "sam@example.com"
}
POST
/api/updateCustomer/Update first name, last name, or email on an owned customer record.
Required permission customer:write
{
"customerId": "CUSTOMER_ID",
"firstName": "Samuel"
}
GET
/api/getCustomer/View the name, phone, and email of an owned customer record.
Required permission customer:read
/api/getCustomer/?customerId=CUSTOMER_ID
