Skip to content

Corksy API (1.2.0)

API for retrieving orders, customers, inventory, wine-club data, and products.

Authentication

This API uses a two-step authentication process:

Step 1: Generate API Key

First, generate your API key from the Admin Settings API page:

  • Go to: https://admin.corksy.io/settings/apiaccess
  • Create a new API key for your application

Step 2: Obtain Bearer Token

Use your API key to obtain a bearer token by making a POST request to the authentication endpoint:

Production:

curl --location 'https://connect-api.corksy.io/v1/auth/public/login' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key-here"
}'

Staging:

curl --location 'https://staging.corksy.io/connect-api/v1/v1/auth/public/login' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key-here"
}'

Response:

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 1800000
}

Step 3: Use Bearer Token

Use the accessToken from the response as a Bearer token in the Authorization header for all subsequent API requests:

Example Requests:

Get Orders:

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Customers:

curl --location 'https://connect-api.corksy.io/v1/customers' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Inventory:

curl --location 'https://connect-api.corksy.io/v1/inventory' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Wine Clubs:

curl --location 'https://connect-api.corksy.io/v1/wine-clubs' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Wine Club Members:

curl --location 'https://connect-api.corksy.io/v1/wine-club-members' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Products:

curl --location 'https://connect-api.corksy.io/v1/products?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Note: The bearer token expires after 30 minutes (1,800,000 microseconds). You'll need to obtain a new token when it expires.

Pagination

All list endpoints support pagination to handle large datasets efficiently. The API uses offset-based pagination with the following parameters:

Pagination Parameters

  • offset (optional): Number of records to skip. Default: 0
  • pageSize (optional): Number of records to return per page. Default: 1000, Maximum: 1000

Pagination Response

Each paginated response includes a pagination object with the following information:

{
  "data": [...],
  "pagination": {
    "current_offset": 0,
    "page_size": 50,
    "total_records": 1250,
    "total_pages": 25,
    "current_page": 1,
    "pages_remaining": 24,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Pagination Examples

First Page (Default):

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer YOUR_TOKEN'

Second Page (50 records per page):

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&offset=50&pageSize=50' \
--header 'Authorization: Bearer YOUR_TOKEN'

Custom Page Size:

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&pageSize=100' \
--header 'Authorization: Bearer YOUR_TOKEN'

Best Practices

  1. Start with the first page (no parameters or offset=0)
  2. Use has_next_page to determine if more pages exist
  3. Increment offset by page_size to get the next page
  4. Choose appropriate page_size based on your needs.
  5. Handle rate limits - each page request counts toward your rate limit
Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Staging Environment
https://staging.corksy.io/connect-api/v1/
Production Environment
https://connect-api.corksy.io/

Authentication

Endpoints related to authentication and authorization

Operations

Orders

Endpoints related to orders

Operations

Customers

Endpoints related to customers

Operations

Inventory

Endpoints related to inventory

Operations

Wine Clubs

Endpoints related to wine clubs

Operations

Wine Club Members

Endpoints related to wine-club members

Operations

Products

Endpoints related to products

Operations

Retrieve a list of products

Request

🚦 Rate Limit: 100 requests / minute

Security
BearerAuth
Query
modifiedFromDatestring(date-time)

Filter products modified from this date (ISO 8601 format). Optional - if not provided, no date filtering is applied.

Example: modifiedFromDate=2025-05-01T00:00:00Z
modifiedToDatestring(date-time)

Filter products modified up to this date (ISO 8601 format). Cannot be specified without modifiedFromDate.

Example: modifiedToDate=2025-05-31T23:59:59Z
offsetinteger>= 0

Number of records to skip for pagination (default: 0)

Example: offset=0
pageSizeinteger[ 1 .. 1000 ]

Number of records to return per page (default: 1000, max: 1000)

Example: pageSize=50
curl -i -X GET \
  'https://staging.corksy.io/connect-api/v1/products?modifiedFromDate=2025-05-01T00%3A00%3A00Z&modifiedToDate=2025-05-31T23%3A59%3A59Z&offset=0&pageSize=50' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

A list of products

Bodyapplication/json
dataArray of objects(Product)
paginationobject(PaginationInfo)
Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "current_offset": 0,
    "page_size": 50,
    "total_records": 1250,
    "total_pages": 25,
    "current_page": 1,
    "pages_remaining": 24,
    "has_next_page": true,
    "has_previous_page": false
  }
}