Free shipping on eligible US orders 1-877-425-2555
CustomGiants

Agentic API

Help a buyer find a display, quote an approved configuration and hand the cart to the customer for review.

Explore the catalog

Use https://customgiants.com/api/v1 as the base URL. Read public retail information directly. Approved integrations send a server-held key in Authorization: Bearer <key>. Approved reseller keys can access wholesale pricing.

Agent credentials carry catalog:read, quotes:read and handoff:write. Reseller credentials also carry orders:write, orders:read, artwork:write and webhooks:write.

  • GET /categories/Find a product family and its slug.
  • GET /products/?category=flags&q=featherSearch product names in a category. The same filters work on the variants endpoint.
  • GET /variants/Find a verified configuration and its SKU. Some product families accept inquiries while supplier data is being confirmed.
  • GET /policies/Read published fulfillment and customer policy information.

Quote a configuration

Send sku and qty to POST /quotes/. Include a two-letter US state and an ISO event_date when the customer has given a destination or deadline. Use a SKU returned by the current catalog.

Read unit, total and savings as integer USD cents. The result includes shipping states and lead and transit days. When an event date is supplied, event_feasible_if_approved_today estimates whether it fits if artwork is approved today. Request a new quote when an item or quantity changes.

Hand a cart to the customer

  1. With an approved agent or reseller key, send an array named lines to POST /handoffs/. Each line contains sku and qty.
  2. Show the returned url directly to the buyer. It lasts 30 minutes. The buyer reviews current retail prices and chooses whether to replace their existing bag.
  3. The buyer supplies their delivery information and completes hosted checkout in the browser. Their artwork goes through proof review before production.

Submit a reseller order

An approved reseller with orders:write can call POST /orders/. Supply an Idempotency-Key, the recipient address, contact email and SKU quantities. Save the original request and reuse its key and body on retries.

A new order returns HTTP 201. A matching retry returns 200 and the existing order. A changed payload with the same key returns 409. If merchant payment setup is pending, a new order returns 503.

  • AddressSend name, street, city, state and zip. Include line2 when needed.
  • FulfillmentSet blind_shipping for eligible configurations. Use reference to link the wholesale order to your own store record.
  • PaymentKeep the returned id, status and account_url with your order. The authorized reseller signs in to that URL to pay.
  • ArtworkSend the reseller's order UUID and an image as multipart fields order and file to POST /artwork/. The returned ticket identifies the support conversation for your reseller account and authorized staff.
  • TrackingUse GET /orders/{uuid}/ with orders:read on the owning reseller account to check status and shipments.

Receive order status updates

Approved resellers can register an HTTPS receiver using POST /webhooks/ with a JSON url. The response returns signing_secret once. Keep it in your server's secret store.

For each incoming order.status message, preserve the raw body. Compute HMAC-SHA256 over the X-CG-Timestamp header value, a period and the original body bytes. Compare the lowercase hexadecimal digest with X-CG-Signature using a timing-safe comparison. Verify freshness and record the event's id before applying its order and status.

Respond with HTTP 2xx after storing the event. Failed deliveries retry with increasing delays for up to ten attempts. Each attempt receives a fresh timestamp. Use the order status endpoint to reconcile a missed update.

Connect your store

Custom application

Keep a confirmed store variant to SKU mapping in your backend. Quote before display, persist a purchase request as an immutable job and give the operator the resulting payment link.

Shopify

A store app can receive a paid-order webhook, verify delivery and queue mapped line items for reseller fulfillment. Store the CustomGiants order UUID with the shop order.

Shopify delivery verification

WooCommerce

Configure an order webhook with a delivery URL and secret. Your adapter verifies the event, checks payment and maps product variations before submitting a reseller request.

WooCommerce webhook setup

Customer-authorized order access

Give the buyer your approved agent identifier. From their order they can grant seven-day status access and revoke it at any time. Send your Bearer credential and the buyer’s token in X-CG-Customer-Grant to the order status endpoint.