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.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

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: Not used
Success: 201

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> · uri
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 "Content-Type: application/json" \
  -d '{
  "name": "string",
  "defaultCurrency": "USD",
  "country": "US"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

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.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Rename a store or change its currency or country

PATCH/v1/stores/{id}

Changes the name, default currency or country of a store. Requires store:manage. Audited.

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

Path parameters

idstringrequired

Request body · application/jsonrequired

namestring
min 1 chars · max 80 chars
defaultCurrencystring
pattern ^[A-Za-z]{3}$
countrystring
pattern ^[A-Za-z]{2}$

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 "Content-Type: application/json" \
  -d '{
  "name": "string",
  "defaultCurrency": "USD",
  "country": "US"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

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: Not used
Success: 200

Path parameters

idstringrequired

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 "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

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.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

List stores

Query parameters

Responses

Create a store

Request body · application/jsonrequired

Responses

Get a store

Path parameters

Responses

Rename a store or change its currency or country

Path parameters

Request body · application/jsonrequired

Responses

Archive a store

Path parameters

Request body · application/jsonrequired

Responses

Store count and limit

Responses