Skip to content

Stores

6 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

List stores

GET/v1/stores

Stores of the merchant, oldest first. Archived stores only with include=archived. defaultCurrency is the store currency, else the merchant default.

Authentication
API key (Bearer)
Permission
store:read
Idempotency-Key
Not used
Success
200

Query parameters

  • includestring

    archived also lists archived stores

    Alwaysarchived

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/stores" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Create a store

POST/v1/stores

Owner/admin (store:manage). Refused with 422 store_limit_reached at the merchant limit and 409 store_name_taken for a duplicate active name. New stores: no routing policy published, pixel consent required, automatic capture. The first store of a self-serve merchant activates it. Audited.

Authentication
API key (Bearer)
Permission
store:manage
Idempotency-Key
Required
Success
201

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • namestringrequired
    min 1 chars · max 80 chars
  • defaultCurrencystringrequired
    pattern ^[A-Za-z]{3}$
  • countrystringrequired
    pattern ^[A-Za-z]{2}$
  • platformstring
    One ofshopifywoocommercecustomDefault custom
  • domainstring
    min 1 chars · max 253 chars
  • returnUrlAllowlistarray<string>

    Return pages the store may send shoppers back to: https origin + path prefix, no wildcards, query or fragment (http://localhost only outside production).

    Default max 20 items

Responses

  • 201Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/stores" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-stores-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "defaultCurrency": "USD",
  "country": "US"
}'
// JSON object. The OpenAPI document does not list its fields.

Get a store

GET/v1/stores/{id}

One store: name, platform, domain, status, default currency, country, return-URL allow-list and routing pause state.

Authentication
API key (Bearer)
Permission
store:read
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/stores/0171fbf6-0276-4ede-aebb-2c142890" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Edit a store (name, currency, country, return-URL allow-list)

PATCH/v1/stores/{id}

Changes the name, default currency, country or the return-URL allow-list (SELL-041: replaces the whole list; https origin + path prefix, no wildcards, query or fragment, http://localhost only outside production; 422 invalid_return_url names each refused entry). Requires store:manage. Audited with the before/after list.

Authentication
API key (Bearer)
Permission
store:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • namestring
    min 1 chars · max 80 chars
  • defaultCurrencystring
    pattern ^[A-Za-z]{3}$
  • countrystring
    pattern ^[A-Za-z]{2}$
  • returnUrlAllowlistarray<string>
    max 20 items

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X PATCH "$GIEP_API_URL/v1/stores/0171fbf6-0276-4ede-aebb-2c142890" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-stores-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "defaultCurrency": "USD",
  "country": "US"
}'
// JSON object. The OpenAPI document does not list its fields.

Archive a store

POST/v1/stores/{id}/archive

Soft delete. Refused (409) for the last active store, while a payment of the store is in flight or awaiting capture (store_payments_in_flight) and while a checkout is live: published checkout, open session or active payment link (store_checkout_live). Archived stores take no payments and keep their history. Audited.

Authentication
API key (Bearer)
Permission
store:manage
Idempotency-Key
Required
Success
200

Path parameters

  • idstringrequired

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • reasonstringrequired
    min 3 chars · max 500 chars

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/v1/stores/0171fbf6-0276-4ede-aebb-2c142890/archive" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-archive-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'
// JSON object. The OpenAPI document does not list its fields.

Store count and limit

GET/v1/stores/usage

Active and archived stores and the merchant store limit (staff-set, default 10).

Authentication
API key (Bearer)
Permission
store:read
Idempotency-Key
Not used
Success
200

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/stores/usage" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.
Stores · API reference · GIEP