Developer Documentation · API v1

Build integrations with the GOAT API.

The GOAT API provides a structured interface for working with products, orders, payments, account status, webhooks, and basic integration workflows. Access is available only to approved partners and internal tools.

Request API Access View Endpoints

Overview

Use the API to connect your application, synchronize resources, create orders, check payment states, and receive webhook notifications.

REST

Predictable resource model

All endpoints follow a clear REST-style structure and return JSON responses with consistent field names.

JSON

Simple request format

Send and receive UTF-8 encoded JSON. Most write operations require an idempotency key.

Webhooks

Event-driven updates

Subscribe to order, payment, and delivery events to keep your system synchronized in real time.

Base URL

All API requests should be sent over HTTPS. The current stable API version is v1.

https://api.goatstore.example/v1

Authentication

Authenticate requests using a bearer token. Keep your API key private and never expose it in client-side code.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

curl -X GET "https://api.goatstore.example/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Pagination

List endpoints support cursor-based pagination. Use the returned next_cursor value to request the next page.

Parameter	Type	Description
`limit`	integer	Number of items to return. Default is 25. Maximum is 100.
`cursor`	string	Pagination cursor from the previous response.

GET/health

Health Check

Returns the current API status, service version, and server time.

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-05-24T12:00:00Z"
}

GET/me

Current Account

Returns information about the API account associated with the provided key.

{
  "id": "acc_01HX9Q9D7P",
  "name": "Partner Account",
  "environment": "production",
  "permissions": ["products:read", "orders:write", "payments:read"]
}

GET/products

List Products

Returns available products and service categories. Use filters to narrow the response.

curl -X GET "https://api.goatstore.example/v1/products?category=games&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/products/{product_id}

Retrieve Product

Returns detailed information about a single product, including availability, region, platform, and metadata.

POST/orders

Create Order

Creates a new order. For safe retries, pass a unique Idempotency-Key header with every request.

curl -X POST "https://api.goatstore.example/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_9f3a2d" \
  -d '{
    "product_id": "prod_01HX9R2Q2C",
    "quantity": 1,
    "customer": {
      "external_id": "user_12345",
      "contact": "customer@example.com"
    }
  }'

GET/orders/{order_id}

Retrieve Order

Returns the current order state, delivery status, payment status, and related timestamps.

{
  "id": "ord_01HX9R8NQ4",
  "status": "processing",
  "payment_status": "pending",
  "delivery_status": "not_started",
  "created_at": "2026-05-24T12:00:00Z"
}

PATCH/orders/{order_id}

Update Order

Updates order metadata, customer reference fields, or internal notes if your API key has write permissions.

GET/payments/{payment_id}

Retrieve Payment

Returns payment details, amount, currency, provider reference, and confirmation status.

POST/webhooks/test

Test Webhook

Sends a test event to the webhook URL configured for your account.

{
  "event": "payment.succeeded",
  "data": {
    "order_id": "ord_01HX9R8NQ4",
    "payment_id": "pay_01HX9S0H5Y",
    "amount": 1490,
    "currency": "RUB"
  }
}

Rate Limits

Rate limits are applied per API key and may vary depending on account type. Responses include rate-limit headers when available.

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the current window.
`X-RateLimit-Remaining`	Number of requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the rate-limit window resets.

Error Handling

Errors use standard HTTP status codes and return a consistent JSON body.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is missing a required field.",
    "request_id": "req_01HX9WZQ7M"
  }
}

Status	Meaning	Recommended Action
`400`	Invalid request	Check required fields and request format.
`401`	Unauthorized	Verify your API key and authorization header.
`403`	Forbidden	Request additional permissions from the administrator.
`404`	Not found	Confirm the resource ID and endpoint path.
`429`	Rate limit exceeded	Wait until the rate-limit window resets.
`500`	Server error	Retry later or contact support with the request ID.