ShowGrow logo
ShowGrow logo
0 $0.00

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.

List locations with cURL
curl 'https://my.showgrow.com/api/v1/locations' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Place a pickup order

  1. Pick a location and products. Call GET /locations and use its location ID with GET /inventory.
  2. Get a customer ID. Create or reuse your integration's record through POST /customers.
  3. Build the cart. Use your own cartId to open a draft. Set product quantities with the latest version.
  4. Submit and track the order. Confirm the customer's eligibility, submit the cart, and store the orderId to check its status. Payment is handled at pickup.

Endpoint reference

Inventory

GET /api/v1/locations List storefront locations.

Required permission inventory:read

Example request
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.

Required permission inventory:read

Request fields
FieldDetails
locationIdQueryLocation ID from GET /locations. Required when the storefront has multiple locations.
limitQueryPage size. Defaults to 50.
cursorQueryOpaque 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.

Example request
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.

Required permission cart:write

Request fields
FieldDetails
cartIdPathYour stable cart reference, up to 80 letters, numbers, hyphens, or underscores.
locationIdJSONLocation ID from GET /locations. Required when the storefront has multiple locations.
customerIdJSONCustomer 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.

Example request
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.

Required permission cart:read

Request fields
FieldDetails
cartIdPathYour stable cart reference, up to 80 letters, numbers, hyphens, or underscores.
Example request
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.

Required permission cart:write

Request fields
FieldDetails
cartIdPathYour stable cart reference, up to 80 letters, numbers, hyphens, or underscores.
productIdPathProduct ID from inventory.
versionJSON · requiredVersion from the last cart response.
quantityJSON · requiredNew total quantity for this product.
Idempotency-KeyHeader · requiredUnique key for this cart operation. Reuse it when retrying the same request.
Example 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.

Required permission cart:write

Request fields
FieldDetails
cartIdPathYour stable cart reference, up to 80 letters, numbers, hyphens, or underscores.
lineIdPathLine ID from the cart response.
versionQuery · requiredVersion from the last cart response.
Idempotency-KeyHeader · requiredUnique key for this cart operation. Reuse it when retrying the same request.
Example 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.

Required permission cart:submit

Request fields
FieldDetails
cartIdPathYour stable cart reference, up to 80 letters, numbers, hyphens, or underscores.
versionJSON · requiredVersion from the last cart response.
customerIdJSONCustomer ID issued to this integration.
ageConfirmedJSON · requiredConfirm that the customer is eligible to purchase.
orderNotesJSONPickup notes.
Idempotency-KeyHeader · requiredUnique 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.

Example request
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.

Required permission orders:read

Request fields
FieldDetails
orderIdPathOrder ID returned at submission.

Use the orderId returned at submission. The storefront owns fulfillment and cancellation.

Example request
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.

Required permission customer:write

Request fields
FieldDetails
phoneJSON · requiredUS phone number.
firstNameJSON · requiredFirst name.
lastNameJSONLast name.
emailJSONEmail 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.

Example request
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.

Required permission customer:read

Request fields
FieldDetails
customerIdPathCustomer ID issued to this integration.
Example request
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.

Required permission customer:write

Request fields
FieldDetails
customerIdPathCustomer ID issued to this integration.
firstNameJSONFirst name.
lastNameJSONLast name.
emailJSONEmail address. An empty string clears it.

Supply at least one field. The phone number is fixed.

Example request
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.

StatusWhat to check
400Invalid request. Check the path, headers, and required fields.
401Invalid key. Check the bearer key, its expiration, and the storefront that issued it.
403Access denied. Check the key permission and storefront settings.
404Resource unavailable. Check the path or resource ID. Carts, orders, and customers belong to the integration that created them.
409Conflict. For CART_VERSION_CONFLICT, read the latest cart before retrying. For IDEMPOTENCY_CONFLICT, use a new idempotency key for a different operation.
415Unsupported content type. Send JSON bodies as application/json.
429Request limit reached. Wait for the number of seconds in Retry-After.
503Service 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

Image preview