Getting Started

Schema is a cloud ecommerce platform that offers a wide range of standard features designed for flexibility and performance. The API can be extended and customized to fit the varying needs of creative online retailers.

The following docs provide a reference to API concepts and usage.

Setup

Login or create a free account.

  1. Get your key from Admin > Settings > API Keys

  2. Install an API client
  3. Connect to the server
require('/path/to/schema-php-client/lib/Schema.php');

$client = new \Schema\Client('<client-id>', '<client-key>');
var Schema = require('schema-client')

var client = new Schema.Client('<client-id>', '<client-key>');
import schema

client = new schema.client({'id': '<client-id>', 'key': '<client-key>'});
require 'schema'

client = Schema::Client.new({'id': '<client-id>', 'key': '<client-key>'});
# Using HTTP Basic Auth
curl https://client_id:client_key@api.schema.io/:options

Examples

// Get a record by ID
$record = $client->get('/products/{id}', array(
    'id' => '...'
));

// Get a collection of records with field criteria
$records = $client->get('/products', array(
    'active' => true
));

// Loop over a collection of records
foreach ($records as $record) {

    // Access a simple field
    $record['id']; // 553ee8a352279905269c60eb

    // Access a link field
    $record['categories']; // Array(...)
}

// Update a record by ID
$result = $client->put('/products/{id}', array(
    'id' => '...',
    'active' => true
));

// Create a new record
$result = $client->post('/products', array(
    'name' => 'New Product',
    'sku' => 'T1000',
    'active' => true
));

// Delete a record by ID
$result = $client->delete('/products/{id}', array(
    'id' => '...'
));
// Get a record by ID
client.get('/products/{id}', {
    id: '...'
}, function(record) {
    ...
});

// Get a collection of records with field criteria
client.get('/products', {
    active: true
}, function(records) {
    ...
});

// Loop over a collection of records
records.each(function(record) {

    // Access a simple field
    record.id; // 553ee8a352279905269c60eb

    // Access a link field
    record.categories(function(results) {
        ...
    });
});

// Update a record by ID
client.put('/products/{id}', {
    id: '...',
    active: true
}, function(result) {
    ...
});

// Create a new record
client.post('/products', {
    name: 'New Product',
    sku: 'T1000',
    active: true
}, function(result) {
    ...
});

// Delete a record by ID
client.delete('/products/{id}', {
    id: '...'
}, function(result) {
    ...
});
# Get a record by ID
curl https://api.schema.io/products/5408dd2b3bdd10b335e6c349

# Get a collection of records with field criteria
curl https://api.schema.io/products?active=true

# Update a record by ID
curl -X PUT https://api.schema.io/products/5408dd2b3bdd10b335e6c349 \
    -d 'active=true'

# Create a new record
curl -X POST https://api.schema.io/products \
    -d 'name=New Product' \
    -d 'active=true' \
    -d 'sku=T1000' \

# Delete a record by ID
curl -X DELETE https://api.schema.io/products/5408dd2b3bdd10b335e6c349

API Concepts

Authentication

Clients authenticate using client_id and client_key params. Native API clients (PHP, NodeJS, etc), should refer to library specific documentation. HTTP clients should authenticate using basic access authentication, where username is your client_id and password is your client_key. For example:

curl https://client_id:client_key@api.schema.io/products

Note: cURL examples may exclude Basic Auth params for brevity

API keys can be created and revoked using the Admin interface.

Methods

All endpoints support REST methods get, put, post, and delete.

GET

Use get to retrieve data. Results may be cached by collection.

// Get a collection of records defined by <model>
$result = $client->get('/<model>');

// Get a single record defined by <model>, identified by <id>
$result = $client->get('/<model>/<id>');

// Get a <field> embedded within a single record defined by <model>, identified by <id>
$result = $client->get('/<model>/<id>/<field>');

// Get a <collection> of records linked from a record defined by <model>, identified by <id>
$result = $client->get('/<model>/<id>/<collection>');

// Example: Get a single stock record from within a product record
$result = $client->get('/products/5408dd2b3bdd10b335e6c349/stock/5408dd2b3bdd10b335e6c359');
// Get a collection of records defined by <model>
client.get('/<model>', function(result) {...});

// Get a single record defined by <model>, identified by <id>
client.get('/<model>/<id>', function(result) {...});

// Get a <field> embedded within a single record defined by <model>, identified by <id>
client.get('/<model>/<id>/<field>', function(result) {...});

// Get a <collection> of records linked from a record defined by <model>, identified by <id>
client.get('/<model>/<id>/<collection>', function(result) {...});

// Example: Get a single stock record from within a product record
client.get('/products/5408dd2b3bdd10b335e6c349/stock/5408dd2b3bdd10b335e6c359', function(result) {...});
# Get a collection of records defined by <model>
curl https://api.schema.io/<model>

# Get a single record defined by <model>, identified by <id>
curl https://api.schema.io/<model>/<id>

# Get a <field> embedded within a single record defined by <model>, identified by <id>
curl https://api.schema.io/<model>/<id>/<field>

# Get a <collection> of records linked from a record defined by <model>, identified by <id>
curl https://api.schema.io/<model>/<id>/<collection>

# Example: Get a single stock record from within a product record
curl https://api.schema.io/products/5408dd2b3bdd10b335e6c349/stock/5408dd2b3bdd10b335e6c359

Return values may represent a collection, record or field. If not found, the server will return a null value with status code 404. Otherwise null values are returned with a status code 200.

See API Querying for more details and use cases.

POST

Use post to create records in a collection, or values in an array.

// Create a record in a collection defined by <model>
$result = $client->post('/<model>', array(...));

// Create a record in a <collection> linked from a record defined by <model>, identified by <id>
$result = $client->post('/<model>/<id>/<collection>', array(...));

// Create an entry in an <array-field> embedded within a record defined by <model>, identified by <id>
$result = $client->post('/<model>/<id>/<array-field>', array(...));

// Example: Create a product stock record
$result = $client->post('/products/5408dd2b3bdd10b335e6c349/stock', array(...));
// Create a record in a collection defined by <model>
client.post('/<model>', {...}, function(result) {...});

// Create a record in a <collection> linked from a record defined by <model>, identified by <id>
client.post('/<model>/<id>/<collection>', {...}, function(result) {...});

// Create an entry in an <array-field> embedded within a record defined by <model>, identified by <id>
client.post('/<model>/<id>/<array-field>', {...}, function(result) {...});

// Example: Create a product stock record
client.post('/products/5408dd2b3bdd10b335e6c349/stock', {...}, function(result) {...});
# Create a record in a collection defined by <model>
curl -X POST https://api.schema.io/<model>

# Create a record in a <collection> linked from a record defined by <model>, identified by <id>
curl -X POST https://api.schema.io/<model>/<id>/<collection>

# Create an entry in an <array-field> embedded within a record defined by <model>, identified by <id>
curl -X POST https://api.schema.io/<model>/<id>/<array-field>

# Example: Create a product stock record
curl -X POST https://api.schema.io/products/5408dd2b3bdd10b335e6c349/stock

The newly created record will be returned. If not found, the server will return a null value with status code 404.

Note: When creating a record, you may pass fields that are not defined by the model. These values wll be stored in the record and can be queried like other fields, but are not type-checked or validated by the server.

PUT

Use put to update records in a collection, or fields in a record.

// Update a record in a collection defined by <model>, identified by <id>
$result = $client->put('/<model>/<id>', array(...));

// Update a <field> embedded within a record defined by <model>, identified by <id>
$result = $client->put('/<model>/<id>/<field>', array(...));

// Example: Update an order's billing information
$result = $client->put('/orders/5408dd2b3bdd10b335e6c349/billing', array(...));
// Update a record in a collection defined by <model>, identified by <id>
client.put('/<model>/<id>', {...}, function(result) {...});

// Update a <field> embedded within a record defined by <model>, identified by <id>
client.put('/<model>/<id>/<field>', {...}, function(result) {...});

// Example: Update an order's billing information
client.put('/orders/5408dd2b3bdd10b335e6c349/billing', {...}, function(result) {...});
# Update a record in a collection defined by <model>, identified by <id>
curl -X PUT https://api.schema.io/<model>/<id>

# Update a <field> embedded within a record defined by <model>, identified by <id>
curl -X PUT https://api.schema.io/<model>/<id>/<field>

# Example: Update an order's billing information
curl -X PUT https://api.schema.io/orders/5408dd2b3bdd10b335e6c349/billing

The updated record or field value will be returned. If not found, the server will return a null value with status code 404.

When updating a record, you may pass fields that are not defined by the model. These values wll be stored in the record and can be queried like other fields, but are not type-checked or validated by the server.

PUT: $unset

Use the $unset key in a put request to remove fields from a record.

// Remove the presence of one or more fields from a record
$result = $client->put('/<model>/<id>', array('$unset' => 'field1, field2, ...'));
// Remove the presence of one or more fields from a record
client.put('/<model>/<id>', {$unset: 'field1, field2, ...'}, function(result) {...});
# Remove the presence of one or more fields from a record
curl -X PUT https://api.schema.io/<model>/<id> \
    -d '$unset=field1,field2,...' \

DELETE

Use delete to remove records from a collection, or fields in a record.

// Remove a record from a collection defined by <model>, identified by <id>
$result = $client->delete('/<model>/<id>');

// Remove the value of a <field> embedded within a record defined by <model>, identified by <id>
$result = $client->delete('/<model>/<id>/<field>');

// Example: Delete a category
$result = $client->delete('/categories/5408dd2b3bdd10b335e6c349');
// Remove a record from a collection defined by <model>, identified by <id>
client.delete('/<model>/<id>', function(result) {...});

// Remove the value of a <field> embedded within a record defined by <model>, identified by <id>
client.delete('/<model>/<id>/<field>', function(result) {...});

// Example: Delete a category
client.delete('/categories/5408dd2b3bdd10b335e6c349', function(result) {...});
# Remove a record from a collection defined by <model>, identified by <id>
curl -X DELETE https://api.schema.io/<model>/<id>

# Remove the value of a <field> embedded within a record defined by <model>, identified by <id>
curl -X DELETE https://api.schema.io/<model>/<id>/<field>

# Example: Delete a category
curl -X DELETE https://api.schema.io/categories/5408dd2b3bdd10b335e6c349

If a resource is found by url, the deleted record or field value will be returned. If not found, the server will return a null value with status code 404.

Errors

Any put or post request may return errors based on validation rules. Errors results are formatted as an object, where the key represents a field and the value represents details of an error.

{
    "errors": {
        "email": {
            "message": "Required",
            "code": "REQUIRED"
        },
        ...
    }
}

Nested errors are returned with a compound key representing the field path.

{
    "errors": {
        "items.quantity": {
            "message": "Must not exceed 1000000",
            "code": "MAXVAL"
        },
        ...
    }
}

API clients should always handle errors from put and `post requests.

$result = $client->post('/accounts', array(...));

if ($result['errors']) {
    // Handle errors
} else {
    // Handle success
}
client.post('/accounts', {...}, function(result) {
    if (result.errors) {
        // Handle errors
    } else {
        // Handle success
    }
});
# Not applicable

Querying

There are many query parameters that may affect the scope of a get request.

Standard Query Parameters

  • where: Set of field criteria to match records
  • sort: Expression used to order record results
  • limit: Maximum number of records to return, or null for unlimited
  • page: Page number used in pagination
  • window: Number of pages to consider in pagination
  • group: Group query used in aggregation
  • search: String to match records by search fields
  • expand: Link fields to expand in a query result
  • include: Additional get queries to include as fields in a result

Note: If a field name collides with a standard query parameter, use the where parameter to disambiguate.

// Retrieve records with fields that collide with a standard parameter
$results = $client->get('/products', array(
    'where' => array('window' => 5)
));
// Retrieve records with fields that collide with a standard parameter
client.get('/products', {
    where: {window: 5}
}, function(results) {
    ...
});
# Retrieve records with fields that collide with a standard parameter
curl https://api.schema.io/products?where[window]=5

Query parameter usage is explained in sections that follow.

MongoDB Compatibility

Schema supports query operators that are compatible with MongoDB, including most operators documented in the MongoDB Manual (Query and Projection Operators).

// Query with Mongo compatible operators
$result = $client->get('/products', array(
    '$or' => array(
        array('size' => array('$gt' => 2, '$lt' => 10)),
        array('size' => null)
    )
));
// Query with Mongo compatible operators
client.get('/products', {
    $or: [
        {size: {$gt: 2, $lt: 10}},
        {size: null}
    ]
}, function(result) {
    ...
});
# Query with Mongo compatible operators
curl https://api.schema.io/products?$or[0][size][$gt]=2&$or[0][size][$lt]=1

Query: Criteria

When specifying criteria in a get request, only records matching all criteria will be returned.

// Find accounts where balance > 0 AND created in the last 24 hours
$results = $client->get('/accounts', array(
    'balance' => array('$gt' => 0),
    'date_created' => array('$gt' => time()-36400)
));
// Find accounts where balance > 0 AND created in the last 24 hours
client.get('/accounts', {
    balance: {$gt: 0},
    date_created: {$gt: Date.now()-36400}
}, function(results) {
    ...
});
# Find accounts where balance > 0 AND created after Jan 1 2000 (GMT)
curl https://api.schema.io/accounts?balance[$gt]=0&date_created[$gt]=2000-01-01T00:00:00Z

Query: Search

Search a collection using the get method with a search string parameter.

// Find products that contain the string 'red'
$results = $client->get('/products', array('search' => 'red'));
// Find products that contain the string 'red'
client.get('/products', {search: 'red'}, function(results) {
    ...
});
# Find products that contain the string 'red'
curl https://api.schema.io/products?search=red

Records will be returned where searchable fields (i.e. name) match the search string provided.

Search fields are configured in a model. See Data Modeling for more information.

Currently, search uses case-insensitive regular expression matching. This works for simple cases but is not ideal for product search, where fuzzy or phonetic matching is preferred. See the Product Roadmap for a an estimate on our plan to support fuzzy and phonetic matching.

Query: Sort

Sort query results using the sort parameter.

// Get accounts sorted by last name in descending alphabetical order
$results = $client->get('/accounts', array('sort' => 'last_name desc'));
// Get accounts sorted by last name in descending alphabetical order
client.get('/accounts', {sort: 'last_name desc'}, function(results) {
    ...
});
# Get accounts sorted by last name in descending alphabetical order
curl https://api.schema.io/accounts?sort=last_name+desc

The sort format consists of <field> <direction>, that is a field name, followed by a space, followed by a direction indicator. Direction is recognized as a full word (i.e. 'ascending' and 'descending') or as abbreviated (i.e. 'asc' and 'desc'). Direction is not case sensitive.

You can combine multiple sort fields in a string.

'last_name desc, first_name desc, balance asc'

Or array.

['last_name desc', 'first_name desc', 'balance asc']

Query: Expand

Expand links in query results using the expand parameter.

// Get a category with products expanded
$result = $client->get('/categories/tasty-treats', array('expand' => 'products'));
// Get a category with products expanded
client.get('/categories/tasty-treats', {expand: 'products'}, function(result) {
    ...
});
# Get a category with products expanded
curl https://api.schema.io/categories/tasty-treats?expand=products

Result includes expanded field data.

{
    "id": "5407e0769fe97f9d4c712a5d",
    ...
    "products": {
        "count": 12,
        "results": [
            {
                "id": "5407e0929fe97f9d4c712a5e",
                ...
            },
            {
                "id": "5421d760a56462a55fd933a5",
                ...
            },
            ...
        ]
    }
}

You can expand up to 5 levels of nested links.

// Get account with nested expand results
$result = $client->get('/accounts/5407e0769fe97f9d4c712a5d', array(
    'expand' => 'orders.invoices.credits'
));
// Get account with deeply nested expand query
client.get('/accounts/5407e0769fe97f9d4c712a5d', {
    expand: 'orders.invoices.credits'
}, function(result) {
    ...
});
# Get a category with products expanded
curl https://api.schema.io/accounts/5407e0769fe97f9d4c712a5d?expand=orders.invoices.credits

In the example above, the result will include refunds belonging to credits belonging to invoices belonging to orders belonging to the account with an ID of 5407e0769fe97f9d4c712a5d.

{
    "id": "5407e0769fe97f9d4c712a5d",
    ...
    "orders": {
        "count": 3,
        "results": [
            {
                "id": "551f571a4f172353736a7a6d",
                ...
                "invoices": {
                    "count": 1,
                    "results": [
                        {
                            "id": "542b07655b2d60884689717c",
                            ...
                            "credits": {
                                "count": 1,
                                "results": [
                                    {
                                        "id": "5408dd2b3bdd10b335e6c349",
                                        ...
                                    }
                                ]
                            }
                        }
                    ]
                }
            },
            ...
        ]
    }
}

You can combine multiple expand fields in a string.

'products, parent, children'

Or array.

['products', 'parent', 'children']

Query: Include

Include multiple sources of data in single a query using the include parameter.

// Include product settings with a product result
$results = $client->get('/products/5407e0769fe97f9d4c712a5d', array(
    'include' => array(
        'settings' => array(
            'url' => '/settings/products'
        )
    )
));
// Include product settings with a product result
client.get('/products/5407e0769fe97f9d4c712a5d', {
    include: {
        settings: {
            url: '/settings/products'
        }
    }
}, function(results) {
    ...
});
# Include product settings with a product result
curl https://api.schema.io/products/5407e0769fe97f9d4c712a5d?include[settings][url]=/settings/products

A record query returns a field representing the include result.

{
    {
        "id": "5407e0769fe97f9d4c712a5d",
        ...
        "settings": {
            ...
        }
    }
}

A collection query returns the include result in each individual record. This allows you to include data related to reach record, and where a direct link does not exist in the model.

$results = $client->get('/accounts', array(
    'include' => array(
        'payments' => array(
            'url' => '/payments',
            'params' => array(
                'account_id' => 'id'
            )
        )
    )
));
client.get('/accounts', {
    include: {
        payments: {
            url: '/payments',
            params: {
                account_id: 'id'
            }
        }
    }
}, fuction(results) {
    ...
});
curl https://api.schema.io/accounts?include[payments][url]=/payments&include[payments][params][account_id]=id

In the example above, the include query uses params to substitute the account ID. The result is a collection of account records, each with a payments field containing only payment records where account_id matches that of the individual account record.

{
    "count": 731,
    "results": [
        {
            "id": "54de8c4e66ea784f11ac3d53",
            ...
            "payments": {
                ...
            }
        },
        {
            "id": "5421d3b5a56462a55fd9339f",
            ...
            "payments": {
                ...
            }
        },
        ...
    ]
}

Query: Count

Retrieve a count of results matching a query using :count.

$count = $client->get('/products/:count', array(
    'active' => true
));
client.get('/products/:count', {
    active: true
}, function(count) {
    // 746
});
curl https://api.schema.io/products/:count?active=true

Result will be an integer value representing the number of matching records.

Linking

Link fields describe a relationship between a specific model and another resource.

{
    "name": "categories",
    "fields": {
        "id": {
            "type": "objectid"
        },
        ...
        "products": {
            "type": "link",
            "model": "products",
            "params": {
                "category_id": "id"
            }
        }
    },
    ...
}

Link fields encapsulate the parameters that define the relationship such as which model is referred to, a key field which contains a foreign key, params which describe additional field mappings, data which specify static value mappings, and/or a url string.

Example: Link to a collection of records

{
    ...
    "fields": {
        "my_products": {
            "type": "link",
            "model": "products"
        }
    }
    ...
}

Example: Link to a record with foreign key

{
    ...
    "fields": {
        "my_product_id": {
            "type": "objectid"
        },
        "my_product": {
            "type": "link",
            "model": "products",
            "key": "my_product_id"
        }
    }
    ...
}

Example: Link to a collection with data values

{
    ...
    "fields": {
        "my_specific_product": {
            "type": "link",
            "model": "products",
            "data": {
                "sku": "T1000"
            }
        }
    }
    ...
}

Example: Link to a record with url and query params.

{
    ...
    "fields": {
        "pending_invoices": {
            "type": "link",
            "url": "/invoices?order_id={id}&status=pending"
        }
    }
    ...
}

Link fields represent a resource and will react to any request as if the resource were directly targeted.

// Retrieve a linked collection
$result = $client->get('/orders/{id}/pending_invoices', array(
    'id' => '542b07655b2d60884689717c'
));
// Retrieve a linked collection
client.get('/orders/{id}/pending_invoices', {
    id: 542b07655b2d60884689717c,
    ...
}, function(result) {
    ...
});
# Retrieve a linked collection
curl https://api.schema.io/orders/542b07655b2d60884689717c/pending_invoices

Aggregation

Group and aggregate data with group or aggregation parameters.

// Get order stats grouped by day, between a date range
$stats_by_day = $client->get('/orders', array(
    'group' => array(
        'count' => array('$sum' => 1),
        'sub_total' => array('$sum' => 'sub_total'),
        'avg_total' => array('$avg' => 'sub_total'),
        'day' => array('$dayOfMonth' => 'date_created'),
        'month' => array('$month' => 'date_created'),
        'year' => array('$year' => 'date_created')
    ),
    'where' => array(
        '$and' => array(
            array('date_created' => array('$gt' => '2015-01-01T00:00:00Z')),
            array('date_created' => array('$lt' => '2016-01-01T00:00:00Z'))
        )
    )
));
// Get order stats grouped by day, between a date range
client.get('/orders', {
    group: {
        count: {$sum: 1},
        sub_total: {$sum: 'sub_total'},
        avg_total: {$avg: 'sub_total'},
        day: {$dayOfMonth: 'date_created'},
        month: {$month: 'date_created'},
        year: {$year: 'date_created'}
    },
    where: {
        $and: [
            {date_created: {$gt: '2015-01-01T00:00:00Z'}},
            {date_created: {$lt: '2016-01-01T00:00:00Z'}}
        ]
    }
}, function(statsByDay) {
    ...
});
# Get order stats grouped by day, between a date range
curl -G https://api.schema.io/orders \
    -d 'group[count][$sum]=1' \
    -d 'group[sub_total][$sum]=sub_total' \
    -d 'group[avg_total][$avg]=sub_total' \
    -d 'group[day][$dayOfMonth]=date_created' \
    -d 'group[month][$month]=date_created' \
    -d 'group[year][$year]=date_created' \
    -d 'where[$and][0][date_created][$gt]=2015-01-01T00:00:00Z' \
    -d 'where[$and][1][date_created][$lt]=2016-01-01T00:00:00Z' \

Result will be a collection of data points grouped by day, with fields count, sub_total, and avg_total.

{
    "count": 30,
    "results": [
        {
            "count": 214,
            "sub_total": 7536.310,
            "avg_total": 35.216,
            "date": 30,
            "month": 5,
            "year": 2015
        },
        {
            "count": 178,
            "sub_total": 5870.850,
            "avg_total": 32.977,
            "date": 29,
            "month": 5,
            "year": 2015
        },
        ...

    ]
}

Pagination

Paginate through a collection of records with page and limit.

// Retrieve page two of a collection, return up to 25 results per page
$page_2_results = $client->get('/orders', array(
    'page' => 2,
    'limit' => 25
));
// Retrieve page two of a collection, return up to 25 results per page
client.get('/orders', {
    'page' => 2,
    'limit' => 25
}, function(page_2_results) {
    ...
});
# Retrieve page two of a collection, return up to 25 results per page
curl https://api.schema.io/orders?page=2&limit=25

Result

{
    "count": 4383,
    "results": [

    ],
    "page": 2,
    "pages": {
        "1": {
            "start": 1,
            "end": 10
        },
        "2": {
            "start": 11,
            "end": 20
        },
        "3": {
            "start": 21,
            "end": 30
        },
        ...
    }
}

The most common use for pagination is to display page numbers and links on a web site. This can be implemented easily using the pages parameter of a collection result.

Example: Display pagination links (PHP)

$result = $client->get('/products', array('active' => true));

$current_page = $result['page'];
$current_range = $result['pages'][$current_page];

echo 'Showing products '.$current_range['start'].' - '.$current_range['end'].' of '.$result['count'];

foreach ($result['pages'] as $page => $range) {
    echo '<a href="?page='.$page.'">Page '.$page.'</a>';
}

Following example shows how to iterate through pages to process a large number of records sequentially.

$current_page = 1;
do {
    $orders = $client->get('/orders', array(
        'limit' => 50,
        'page' => $current_page
    ));
    foreach ($orders as $order) {
        ... process order ...
    }
    $current_page++;
}
while (isset($orders['pages'][$current_page]));
var async = require('async');

var orders = null;
var currentPage = 1;

async.doWhilst(
    function(doneWithPage) {
        client.get('/orders', {
            limit: 50,
            page: currentPage
        }, function(orderPage) {
            orders = orderPage;
            if (orderPage && orderPage.results.length) {
                async.each(orderPage.results,
                    function(order, doneWithOrder) {
                        ... process order ...
                        doneWithOrder();
                    },
                    function() {
                        doneWithPage();
                    }
                );
            } else {
                doneWithPage();
            }
        });
    },
    function() {
        currentPage++;
        return orders && orders.pages && orders.pages[currentPage];
    },
    function() {
        // Completed
        ...
    }
);
# Not applicable

Caching

API clients should generally handle cache management for you. Please refer to client documentation for instructions on how to setup and maintain client cache.

Schema supports caching primarily at the collection level.

Collection Cache

The server stores a version number for each collection that is automatically incremented on update.

All requests to a particular collection can be cached without needing to check individual records. This approach has dramatic performance benefits on collections which do not frequently change, such as Products.

When a client connects to the API, it exchanges collection version info.

{"com.products": 1471, "com.orders": 89412, "com.accounts": 5726, ...}

The server compares client versions with local versions and returns only versions that are changed.

{"com.products": 1472, ...}

The client invalidates all cached records of a collection with new versions.

If a cached result contains expanded link data, it will be indexed by each collection which contributes to the result. For example, a cached query that returns product and category data combined, will be invalidated if either product or category collections are updated.

Webhooks

Webhooks can be used to notify your application about events that happen in a Schema account. Configuring a webhook means to specify an endpoint URL that should be notified by Schema, and an array of events that should trigger a notification.

Events are recorded in your account regardless of whether a webhook is configured to receive it, which allows your application to query /events at any time to recover from down time or just to act on past events.

Note: Events are enabled for paid plans only.

A new webhook may be registered in the Admin, or using the API itself. When creating a webhook from a script, you should use alias to refer to a specific configuration. This allows you to easily update an existing endpoint.

// Create or update webhook with the alias 'example'
// Note: make sure your script does not execute this on each request
$client->put('/:webhooks/example', array(
    'url' => 'https://yourserver.com/webhook',
    'alias' => 'example',
    'events' => array(
        'product.updated',
        'order.submitted',
        'payment.succeeded'
    )
));
// Create or update webhook with the alias 'example'
client.put('/:webhooks/example', {
    url: 'https://yourserver.com/webhook',
    alias: 'example',
    events: [
        'product.updated',
        'order.submitted',
        'payment.succeeded'
    ]
});
# Create or update webhook with the alias 'example'
curl -X PUT https://api.schema.io/:webhooks/example \
    -d 'url=https://yourserver.com/webhook' \
    -d 'alias=example' \
    -d 'events[]=product.updated' \
    -d 'events[]=order.submitted' \
    -d 'events[]=payment.succeeded' \

A complete webhook example implementation can be found on GitHub at https://github.com/schemaio/schema-webhooks-example.

Receiving a webhook

Webhook endpoints are no different than other pages on your website. Data is sent as JSON in a POST body. The payload represents a single event with different attributes based on the event type.

created events contain the id of a newly created record.

{
    "id": "58991ed385c95b9e2e0aa433",
    "date_created": "2017-02-07T01:11:47.219Z",
    "model": "invoices",
    "type": "invoice.created",
    "data": {
        "id": "58991ed285c95b9e2e0aa42c"
    }
}

updated events contain the id of an existing record, plus attributes that have changed in the update.

{
    "id": "58991ed385c95b9e2e0aa431",
    "date_created": "2017-02-07T01:11:47.219Z",
    "model": "orders",
    "type": "order.updated",
    "data": {
        "id": "58991eb385c95b9e2e0aa428",
        "paid": true,
        "payment_total": 23.85,
        "status": "delivery_pending"
    }
}

deleted events contain the id of a record after deletion.

{
    "id": "58929125c858fb88ca5db423",
    "date_created": "2017-02-07T01:11:47.219Z",
    "model": "products",
    "type": "product.deleted",
    "data": {
        "id": "5892910fc858fb88ca5db41f"
    }
}

Your webhook might need to fetch the associated record using data.id before performing a relevant action.

Other events may contain additional data attributes that are useful in processing the event.

Receiving webhooks with an HTTPS server

You may use an HTTPS URL for your webhook endpoint. In that case, Schema will validate the connection to your server is secure before sending webhook data. Your server must be correctly configured to support HTTPS with a valid server certificate.

Responding to a webhook

Your endpoint must respond to successful requests with a 2xx HTTP status code. All other information returned by your script will be ignored. Response codes outside this range will indicate that you were not able to receive the webhook event.

If a webhook is not acknowledged successfully, Schema will continue trying to send it once every hour for up to 2 days. After this time, we will send an email alert and continue attempting to deliver the webhook every hour. If your endpoint does not respond after 7 days, you will be notified finally and the webhook will be disabled until further action is taken.

Types of events

This is a list of all the events we currently send. We may add more at any time.

account.created Occurs when a new customer account is created.
account.updated Occurs when an existing customer account is updated.
account.deleted Occurs when a customer account is deleted.
account.card.created Occurs when a new customer card is created.
account.card.updated Occurs when an existing customer card is updated.
account.card.deleted Occurs when a customer card is deleted.
account.address.created Occurs when a new customer address is created.
account.address.updated Occurs when an existing customer address is updated.
account.address.deleted Occurs when a customer address is deleted.
account.credit.created Occurs when a new customer credit is created.
account.credit.updated Occurs when an existing customer credit is updated
account.credit.deleted Occurs when a customer credit is deleted.
cart.created Occurs when a new shopping cart is created.
cart.deleted Occurs when a shopping cart is deleted.
cart.converted Occurs when a shopping cart is converted to an order.
cart.abandoned Occurs when a shopping cart has no activity for 3 hours.
category.created Occurs when a new category is created.
category.updated Occurs when an existing category is updated.
category.deleted Occurs when a category is deleted.
category.product.added Occurs when a product is added to a category.
category.product.removed Occurs when a product is removed from a category.
contact.created Occurs when a new contact is created.
contact.updated Occurs when an existing contact is updated.
contact.deleted Occurs when a contact is deleted.
coupon.created Occurs when a new coupon is created.
coupon.updated Occurs when an existing coupon is updated.
coupon.deleted Occurs when a coupon is deleted.
coupon.code.created Occurs when a new coupon code is created.
coupon.code.deleted Occurs when a coupon code is deleted.
coupon.generation.completed Occurs when a coupon code generation is completed.
credit.created Occurs when a new credit memo is created.
credit.updated Occurs when an existing credit memo is updated.
credit.deleted Occurs when a credit memo is deleted.
credit.refund_succeeded Occurs when a credit memo refund has succeeded.
credit.refund_failed Occurs when a credit memo refund has failed.
invoice.created Occurs when a new invoice is created.
invoice.updated Occurs when an existing invoice is updated.
invoice.deleted Occurs when an invoice is deleted.
invoice.payment_succeeded Occurs when an invoice payment has succeeded.
invoice.payment_failed Occurs when an invoice payment has failed.
order.created Occurs when a new order is created.
order.updated Occurs when an existing order is updated.
order.deleted Occurs when an order is deleted.
order.submitted Occurs when an order is submitted, as opposed to a draft.
order.canceled Occurs when an order is canceled.
order.paid Occurs when an order is fully paid, resulting in a zero balance.
order.delivered Occurs when an order is completely fulfilled.
page.created Occurs when a new page is created.
page.updated Occurs when an existing page is updated.
page.deleted Occurs when a page is deleted.
page.article.created Occurs when a new page article is created.
page.updated Occurs when an existing page article is updated.
page.deleted Occurs when a page article is deleted.
payment.succeeded Occurs when a payment has succeeded.
payment.failed Occurs when a payment has failed.
payment.voided Occurs when a payment is voided before closing.
payment.refund.succeeded Occurs when a refund has succeeded.
payment.refund.failed Occurs when a refund has failed.
payment.refund.voided Occurs when a refund is voided before closing.
product.created Occurs when a new product is created.
product.updated Occurs when an existing product is updated.
product.deleted Occurs when a product is deleted.
product.stock_adjusted Occurs when product stock has been adjusted, manually or by an order.
product.variant.created Occurs when a new product variant is created.
product.variant.updated Occurs when an existing product variant is updated.
product.variant.deleted Occurs when a product variant is deleted.
product.review.created Occurs when a new product review is created.
product.review.updated Occurs when an existing product review is updated.
product.review.deleted Occurs when a product review is deleted.
promotion.created Occurs when a new promotion is created.
promotion.updated Occurs when an existing promotion is updated.
promotion.deleted Occurs when a promotion is deleted.
setting.updated Occurs when a system setting is updated.
shipment.created Occurs when a new shipment is created.
shipment.updated Occurs when an existing shipment is updated.
shipment.deleted Occurs when a shipment is deleted.
shipment.canceled Occurs when a shipment is canceled.
subscription.created Occurs when a new subscription is created.
subscription.updated Occurs when an existing subscription is updated.
subscription.deleted Occurs when a subscription is deleted.
subscription.activated Occurs when a subscription is activated, with or without a trial.
subscription.trial_will_end Occurs when a subscription trial will end within 3 days.
subscription.canceled Occurs when a subscription is canceled.
subscription.paid Occurs when a subscription is fully paid, resulting in a zero balance.

Data Modeling

Schema supports a range of options for creating and customizing data models.

You can modify standard models such as products, create new models, or extend existing ones. All models are available for inspection using the API endpoint /:models or using the Admin interface.

To get started, use the API to explore standard models.

$product_model = $client->get('/:models/products');

print_r($product_model);
client.get('/:models/products', function(productModel) {
    console.log(productModel);
});
curl https://api.schema.io/:models/products

Add custom fields to standard models.

$client->put('/:models/products', array(
    'fields' => array(
        'my_custom_field' => array(
            'type' => 'string',
            'default' => 'Hello World'
        )
    )
));

print_r($product_model);
client.put('/:models/products', {
    fields: {
        my_custom_field: {
            type: 'string',
            default: 'Hello World'
        }
    }
});
curl -X PUT https://api.schema.io/:models/products \
    -d 'fields[my_custom_field][type]=string' \
    -d 'fields[my_custom_field][default]=Hello World' \

All properties of a model can be modified except id, api and client_id.

Basics

Following are the basic properties defined for all models.

id

Global unique model identifier, determined by a combination of <client_id>.<api>.<name>.

client_id

Id of the client which owns a model if applicable. When a standard model is modified, a new model is automatically created which extends the standard model and receives a client_id.

api

API name that a model belongs to. Schema data architecture supports multiple API groups, the first of which is Commerce, identified as com.

name

Name that identifies a model within an API group. This name also becomes the anchor for a model's API endpoint. For example, a model named animals will be accessible using the endpoint /animals.

version

Current version of a model. Schema uses Semantic Versioning to enable consumer applications to react to data model version changes appropriately.

label

Label of a single record, for display in user interfaces such as Schema Admin.

plural

Plural form of a collection of records, for display in user interfaces such as Schema Admin.

extends

Id of a parent model if extended. An extended model inherits all properties of a parent model unless overridden.

extends_version

Version of a parent model if extended.

fields

Configuration used to convert field data types, defaults, and validation. See Fields Types for more information. Note: Model records may contain fields that are not defined by a model, in which case they are not coerced by the server.

secondary_field

Name of a field used as a secondary key. Most commonly used as a human readable identifier. A product category slug field with a value of clothing is recognized as the first segment in a URI after the model name, for example /categories/clothing. Primary key values should be unique.

name_field

Field used as a name to identify records in user interfaces. If not defined, primary_field is used by default.

query

Configuration of default standard query parameters page, limit, window, and sort. See API Querying for more information on standard query parameters.

features

Configuration of features applied to a model. See Features for more information on available model features.

indexes

Configuration of indexes maintained by a model collection. This capability allows the developer to optimize queries of large data sets.

triggers

Configuration of triggers that are invoked when API requests are made. See Triggers formore information on configuring model triggers.

Fields

Model fields describe the way record data is typed, formatted, and validated by the server.

Fields are configured as an object in a model. Object keys represent field names.

{
    "fields": {
        "name": {
            "type": "string"
        },
        "quantity": {
            "type": "int"
        },
        "active": {
            "type": "bool",
            "default": true
        },
        "things": {
            "type": "array",
            "value_type": "object",
            "fields": {
                "name": {
                    "type": "string"
                }
            }
        },
        ...
    }
}

Data values are automatically type converted in the course of an API request. For example, a string value "true" is converted to boolean value true, while a string value "false" is converted to boolean value false.

All fields are considered optional and nullable unless otherwise configured.

Field Types

Schema supports scalar, composite, and dynamic data types.

Scalar Fields

string

String fields contain a string of characters. There is no specific limit to the length of a string value.

bool

Boolean fields contain either true or false. Values such as 1 and 0 passed to a boolean field will be converted to true and false.

int

Integer fields contain a number value without a decimal. A float value passed to an integer field will be rounded to the nearest whole number.

float

Float fields contain floating point values and may be configured with scale for automatic rounding at a particular decimal length.

currency

Currency fields are similar to float values, except they are automatically rounded according to the default currency scale, and internally stored and converted from integers when performing certain operations.

date

Date fields are represented by an ISO formatted date string such as 2015-05-08T18:41:55.527Z. Internally they are stored as a 64-bit integer that represents the number of milliseconds passed since the Unix epoch (Jan 1, 1970). This results in a representable date range of about 290 million years into the past and future.

A number value passed to a date field will be interpreted as a timestamp and stored accordingly.

objectid

Objectid fields contain a MongoDB ObjectId value. They are used by default to sort records by natural creation order.

Composite Fields

array

Array fields contain multiple values and may be configured with value_type to ensure contained values are converted accordingly.

object

Object fields are used to store key/value pairs. They are equivalent to JSON objects and may be configured with fields to further define the types and properties of object values by key.

collection

Collection fields can be considered as embedded models. They support almost all properties of a model except:

  • Collection records are stored in a separate database collection
  • Collection fields are automatically assigned parent_id (objectid) and parent (link) fields

Collection API endpoints are available as a combination of the model and collection field names.

GET /accounts:credits

In the above example, credits is a child collection of the accounts model as defined by the credits field.

Note: Collection fields are not recognized in a nested field configuration.

Dynamic Fields

link

Links define a relationship with another resource, such as a specific record or collection and may be configured with the following properties.

  • url - Specific url used to locate the linked resource
  • model - Used in absence of a url property to construct a model-based link
  • key - Optional field used as a primary key to construct a model-based link
  • params - Object describing parameters as fields of the model to build a link query
  • data - Object containing static data passed in a link query

If a link field has a model property without a key, the link url will be constructed as /<model>. If a key property is defined, the link url will be constructed as /<model>/<key-value>.

Field Properties

Model fields can be configured with many useful properties.

default

Specify a value that should be assigned by default when a field is not defined at the point of record creation. Default values can be of any type including a formula.

required

Require a field to be defined at the point of record creation. If the field does not exist or is empty, an error will be returned. See API Errors for more information.

readonly

Cause a field to raise an error if a client attempts to modify its value. Read-only field values may be defined by a formula or internal process.

immutable

Cause a field to raise an error if a client attempts to modify its value. Similar to readonly except the value can be initially defined by a client, but cannot be modified or removed in the scope of a single record.

format

Specify a format for string fields used to modify a value and also for display purposes.

  • slug - Format a string value such as "Product Name" into "product-name". Removes non-alphanumeric characters.
  • slugid - Same as slug except period (.) characters are allowed.
  • semver - Format a string value such as "1.2" into "1.2.0". Raises an error if a proper version is not determined.
  • uppercase - Format a string by converting all characters to uppercase.
  • lowercase - Format a string by converting all characters to lowercase.

auto

Cause a field value to be automatically generated under certain conditions.

  • date fields may be auto-assigned to the current date
  • int fields may be auto-assigned an incremental value from a global counter
  • objectid fields may be auto-assigned a new ObjectId value
  • string fields may be auto-assigned with a pattern based on an incremental value from a global counter

Example: Auto increment int field with start value.

{
    "fields": {
        "number": {
            "type": "int",
            "auto": true,
            "increment": {
                "start" 100000
            }
        }
    }
}

Example: Auto increment string field with formula pattern.

{
    "fields": {
        "code": {
            "type": "string",
            "auto": true,
            "increment": {
                "start": 100000,
                "pattern": {
                    "$formula": "alphanum(5) + test_field"
                }
            }
        }
    }
}

formula

Field value should be automatically derived from a formula. See Formulas for more information.

enum

Specify a set of enumerated values. An error is raised if a non-enumerated value is passed.

rules

Array of data validation rules. See Validation for more information.

label

Field label used for user interface display purposes.

description

Field description for documentation and user interface assistance.

multiline

Indicate that user interfaces should consider a string field as multi-line.

Links

Link fields define a relationship with another resource. They are used by the API server and clients to moderate interaction between multiple related records.

Updating Linked Records

When creating a record with put, you may specify linked data to be created or updated in a single transaction.

$result = $client->post('/accounts', array(
    'name' => 'Jane Smith',
    'email' => 'jane@example.com',
    'addresses' => array(
        array(
            'address1' => '123 Nice Place',
            ...
        ),
        ...
    )
));
client.post('/accounts', {
    name: 'Jane Smith',
    email: 'jane@example.com',
    addresses: [
        {
            address1: '123 Nice Place',
            ...
        },
        ...
    ]
}, function(result) {
    ...
});
``` curl
curl -X POST https://api.schema.io/accounts \
    -d 'name=Jane Smith' \
    -d 'email=jane@example.com' \
    -d 'addresses[0][address1]=123 Nice Place' \

If any linked requests fail, the entire transaction will roll back and return.

Links enable the developer to encapsulate complex relationships without passing complexity to consumer applications.

Lazy Loading

Some native API clients can use reflection techniques to implement lazy loading of linked data. This is made possible by the native wire protocol, which returns link metadata for any requested resource.

$order = $client->get('/orders/5527b6fd337029b306748dcb');

print_r($order['account']);

In the above example, the account record is fetched with a new API request on demand.

Formulas

Record values can be derived from a formula within scope of the current record along with several native formula functions. As an example, most basic arthmetic involved in ecommerce calculations can be implemented using formulas.

{
    "fields": {
        "sub_total": {
            "type": "currency",
            "formula": "sum(items.price_total)"
        },
        "discount_total": {
            "type": "currency",
            "formula": "sum(items.discount_total)"
        },
        "tax_total": {
            "type": "currency",
            "formula": "sum(items.tax_total)"
        },
        "grand_total": {
            "type": "currency",
            "formula": "sub_total + tax_total - discount_total"
        }
    }
}

Formula syntax is similar to JavaScript. Fields referenced in a formula with a null or undefined value are auto-converted to an appropriate type. For example, undefined string fields are converted to "", and undefined int fields are converted to 0.

Formula Functions

mixed if(cond, then, [else])
mixed case(var1, val1, [val2], [val3], [...])
bool not(cond)
bool and(cond1, cond2, ...)
bool or(cond1, cond2, ...)
bool nor(cond1, cond2, ...)
string join(string, val1, val2, ...)
string escape(val)
string unescape(val)
string escape_html(val)
string unescape_html(val)
string string(val)
string upper(val)
string lower(val)
string hyphen(val)
string underscore(val)
string camel(val)
string upper(val)
string capital(val)
string words(val)
string slug(val)
string slugid(val)
bool regex(expr, val, [opt])
bool match(expr, val, [opt])
string replace(expr, orig, new, [opt])
ISOString now()
int date([date])
int time([date])
int year([date])
int month([date])
int day([date])
int weekday([date])
int length(val)
string pad_left(str, chr)
string pad_right(str, chr)
string slash_left(val)
string slash_right(val)
string repeat(val, times)
bool contains(val, str)
string strip_tags(html)
string trim(val)
string trim_left(val)
string trim_right(val)
string truncate(val, len)
string alphanum(len, chars)
string md5(val)

Validation

Simple data validation should be implemented with field properties like required and immutable.

Advanced validation can be implemented with field rules which use formula expressions to check the state of various related fields.

{
    "fields": {
        "active": {
            "type": "bool"
        },
        "pending": {
            "type": "bool",
            "rules": [
                {
                    "expression": "if(active, not(pending))",
                    "error": "Record cannot be active while pending"
                }
            ]
        }
    }
}

Each rule expression must evaluate true or else the field will raise an error with a message defined by the error property.

Triggers

Model triggers allow you to perform one or more actions when particular conditions are met during the course of various events.

{
    "triggers": [
        {
            "events": ["update"],
            "conditions": {
                "pending": true
            },
            "actions": [
                {
                    "type": "request",
                    "method": "post",
                    "url": "/notifications?template=things.pending",
                    "params": {
                        "contact": "email",
                        "record_id": "id"
                    }
                }
            ]
        }
    ]
}

Features

Features represent encapsulated functionality that may be invoked by events when configured on a model. This provides the flexibility to configure or disable features as needed.

{
    "name": "accounts",
    ...
    "features": {
        "account": {
            "methods": {
                "login": true
            }
        }
    }
}

Each feature contains one or more methods which may be individually enabled or disabled.

Each feature method defines a set of events that will trigger the method when invoked.

There are several standard features defined by the commerce API.

Commerce Models

Standard ecommerce models are adaptable to a wide range of common use cases.

See the Schema Model Map for a visual overview.

Accounts

Track customer account information and history.

// Create an account
$result = $client->post('/accounts', array(
    'email' => '<account email>',
    'password' => '<account password>',
    'type' => 'individual',
    ...
));

// Retrieve an account
$result = $client->get('/accounts/{id}', array(
    'id' => '<account id>',
    ...
));

// Update an account
$result = $client->put('/accounts/{id}', array(
    'id' => '<account id>',
    ...
));

// Delete an account
$result = $client->delete('/accounts/{id}', array(
    'id' => '<account id>'
));
// Create an account
client.post('/accounts', { 
    email: '<account email>',
    password: '<account password>',
    type: '<account type>',
    ...
}, function(result) {
    ...
});

// Retrieve an account
client.get('/accounts/{id}', { id: '<account id>', ... }, function(result) {
    ...
});

// Update an account
client.put('/accounts/{id}', { id: '<account id>', ... }, function(result) {
    ...
});

// Delete an account
client.delete('/accounts/{id}', { id: '<account id>' }, function(result) {
    ...
});
# Create an account
curl -X POST https://api.schema.io/accounts \ 
    -d 'email=<account email>' \ 
    -d 'password=<account password>' \ 
    -d 'type=<account type>' \ 

# Retrieve an account
curl -G https://api.schema.io/accounts/{id} \
    -d 'id=<account id>' \

# Update an account
curl -X PUT https://api.schema.io/accounts/{id} \
    -d 'id=<account id>' \

# Delete an account
curl -X DELETE https://api.schema.io/accounts/{id} \
    -d 'id=<account id>' \
Account Fields
addresses
Stored addresses used by an account
collection
addresses.active bool Default
addresses.address1 string
addresses.address2 string
addresses.city string
addresses.country string
addresses.date_created date Auto
addresses.date_updated date Auto (update)
addresses.fingerprint string
addresses.first_name string
addresses.id objectid Primary
addresses.last_name string
addresses.name string Name
addresses.parent link → /accounts/{parent_id}
addresses.parent_id objectid Required
Immutable
addresses.phone string Format (phone)
addresses.state string
addresses.zip string
balance
Balance of account credits
currency Read-only
billing
Default account billing information
object
billing.account_card link → /accounts:cards/{account_card_id}
billing.account_card_id objectid
billing.address1 string
billing.address2 string
billing.card object
billing.card.address_check string
billing.card.brand string
billing.card.cvc_check string
billing.card.exp_month int
billing.card.exp_year int
billing.card.gateway string
billing.card.last4 string
billing.card.test bool
billing.card.token string Required
billing.card.zip_check string
billing.city string
billing.country string
billing.first_name string
billing.last_name string
billing.method string
billing.name string Name
billing.phone string
billing.state string
billing.zip string
cards
Stored credit cards used by an account
collection
cards.active bool Default
cards.address_check string
cards.billing object
cards.billing.address1 string
cards.billing.address2 string
cards.billing.city string
cards.billing.country string
cards.billing.first_name string
cards.billing.last_name string
cards.billing.name string Name
cards.billing.phone string Format (phone)
cards.billing.state string
cards.billing.zip string
cards.brand string
cards.cvc_check string
cards.date_created date Auto
cards.date_updated date Auto (update)
cards.exp_month int
cards.exp_year int
cards.fingerprint string
cards.gateway string
cards.id objectid Primary
cards.last4 string
cards.parent link → /accounts/{parent_id}
cards.parent_id objectid Required
Immutable
cards.test bool
cards.token string Required
cards.zip_check string
cart_abandoned_count int
carts link → /carts?account_id=id
contact link → /contacts/{contact_id}
contact_id objectid
contacts link → /contacts?account_id=id
credits
Account credit transactions
collection
credits.amount currency Required
Immutable
credits.credit link → /credits/{credit_id}
credits.credit_id objectid Immutable
credits.currency string
credits.date_created date Auto
credits.date_updated date Auto (update)
credits.id objectid Primary
credits.invoice link → /invoices/{invoice_id}
credits.invoice_id objectid Immutable
credits.number string Auto
Immutable
credits.parent link → /accounts/{parent_id}
credits.parent_id objectid Required
Immutable
credits.payment link → /payments/{payment_id}
credits.payment_id objectid Immutable
credits.reason string
credits.refund link → /payments:refunds/{refund_id}
credits.refund_id objectid Immutable
currency string
date_created date Auto
date_last_login date
date_updated date Auto (update)
email string Required
Format (email)
email_optin bool
first_name string
group
Exclusive group an account may belong to
string
id objectid Primary
invoices link → /invoices?account_id=id
last_name string
name string Name
Formula if(type == 'individual', trim(first_name+' '+last_name), name)
order_count int
order_value currency
orders link → /orders?account_id=id
password
Optionally used to allow/restrict access to account data
string Format (password)
password_reset_key
Optionally provide a one-time use key for password reset
string
password_reset_url
Optionally provide a one-time use URL for password reset
string Format (url)
phone string
segments
Inclusive segments an account may belong to
array
shipping
Default account shipping information
object
shipping.account_address link → /accounts:addresses/{account_address_id}
shipping.account_address_id objectid
shipping.address1 string
shipping.address2 string
shipping.city string
shipping.country string
shipping.first_name string
shipping.last_name string
shipping.name string Name
shipping.phone string
shipping.state string
shipping.zip string
subscriptions link → /subscriptions?account_id=id
type string Immutable
Enumerated (individual, business)
Default

Attributes

// Create an attribute
$result = $client->post('/attributes', array(
    'id' => '<attribute id>',
    'name' => '<attribute name>',
    ...
));

// Retrieve an attribute
$result = $client->get('/attributes/{id}', array(
    'id' => '<attribute id>',
    ...
));

// Update an attribute
$result = $client->put('/attributes/{id}', array(
    'id' => '<attribute id>',
    ...
));

// Delete an attribute
$result = $client->delete('/attributes/{id}', array(
    'id' => '<attribute id>'
));
// Create an attribute
client.post('/attributes', { 
    id: '<attribute id>',
    name: '<attribute name>',
    ...
}, function(result) {
    ...
});

// Retrieve an attribute
client.get('/attributes/{id}', { id: '<attribute id>', ... }, function(result) {
    ...
});

// Update an attribute
client.put('/attributes/{id}', { id: '<attribute id>', ... }, function(result) {
    ...
});

// Delete an attribute
client.delete('/attributes/{id}', { id: '<attribute id>' }, function(result) {
    ...
});
# Create an attribute
curl -X POST https://api.schema.io/attributes \ 
    -d 'id=<attribute id>' \ 
    -d 'name=<attribute name>' \ 

# Retrieve an attribute
curl -G https://api.schema.io/attributes/{id} \
    -d 'id=<attribute id>' \

# Update an attribute
curl -X PUT https://api.schema.io/attributes/{id} \
    -d 'id=<attribute id>' \

# Delete an attribute
curl -X DELETE https://api.schema.io/attributes/{id} \
    -d 'id=<attribute id>' \
Attribute Fields
date_created date Auto
date_updated date Auto (update)
default *
id string Primary
Required
Immutable
Formula underscore(id)
Default
multi bool
name string Name
Required
products link → /products?attributes.{id}[$exists]=true
required bool
type string Enumerated (text, textarea, dropdown, checkbox, radio, image)
values array
visible bool

Blogs

// Create a blog
$result = $client->post('/blogs', array(
    'name' => '<blog name>',
    ...
));

// Retrieve a blog
$result = $client->get('/blogs/{id}', array(
    'id' => '<blog id>',
    ...
));

// Update a blog
$result = $client->put('/blogs/{id}', array(
    'id' => '<blog id>',
    ...
));

// Delete a blog
$result = $client->delete('/blogs/{id}', array(
    'id' => '<blog id>'
));
// Create a blog
client.post('/blogs', { 
    name: '<blog name>',
    ...
}, function(result) {
    ...
});

// Retrieve a blog
client.get('/blogs/{id}', { id: '<blog id>', ... }, function(result) {
    ...
});

// Update a blog
client.put('/blogs/{id}', { id: '<blog id>', ... }, function(result) {
    ...
});

// Delete a blog
client.delete('/blogs/{id}', { id: '<blog id>' }, function(result) {
    ...
});
# Create a blog
curl -X POST https://api.schema.io/blogs \ 
    -d 'name=<blog name>' \ 

# Retrieve a blog
curl -G https://api.schema.io/blogs/{id} \
    -d 'id=<blog id>' \

# Update a blog
curl -X PUT https://api.schema.io/blogs/{id} \
    -d 'id=<blog id>' \

# Delete a blog
curl -X DELETE https://api.schema.io/blogs/{id} \
    -d 'id=<blog id>' \
Blog Fields
active bool
date_created date Auto
date_updated date Auto (update)
id objectid Primary
meta_description string
meta_keywords string
meta_title string
name string Name
Required
posts collection
posts.content string Format (html)
posts.date_created date Auto
posts.date_published date
posts.date_updated date Auto (update)
posts.id objectid Primary
posts.meta_description string
posts.meta_keywords string
posts.meta_title string
posts.name string Name
Required
posts.parent link → /blogs/{parent_id}
posts.parent_id objectid Required
Immutable
posts.published bool
posts.redirect string Format (url)
posts.slug string Format (slug)
Default
posts.summary string Format (html)
posts.tags array
slug string Format (slug)
Default

Carts

// Create a cart
$result = $client->post('/carts', array(
    'name' => '<cart name>',
    ...
));

// Retrieve a cart
$result = $client->get('/carts/{id}', array(
    'id' => '<cart id>',
    ...
));

// Update a cart
$result = $client->put('/carts/{id}', array(
    'id' => '<cart id>',
    ...
));

// Delete a cart
$result = $client->delete('/carts/{id}', array(
    'id' => '<cart id>'
));
// Create a cart
client.post('/carts', { 
    name: '<cart name>',
    ...
}, function(result) {
    ...
});

// Retrieve a cart
client.get('/carts/{id}', { id: '<cart id>', ... }, function(result) {
    ...
});

// Update a cart
client.put('/carts/{id}', { id: '<cart id>', ... }, function(result) {
    ...
});

// Delete a cart
client.delete('/carts/{id}', { id: '<cart id>' }, function(result) {
    ...
});
# Create a cart
curl -X POST https://api.schema.io/carts \ 
    -d 'name=<cart name>' \ 

# Retrieve a cart
curl -G https://api.schema.io/carts/{id} \
    -d 'id=<cart id>' \

# Update a cart
curl -X PUT https://api.schema.io/carts/{id} \
    -d 'id=<cart id>' \

# Delete a cart
curl -X DELETE https://api.schema.io/carts/{id} \
    -d 'id=<cart id>' \
Cart Fields
account link → /accounts/{account_id}
account_credit_amount
Amount of account credit to spend for automatic payment
currency
account_id objectid
active bool Formula if(order_id, false, active)
Default
billing object
billing.account_card link → /accounts:cards/{account_card_id}
billing.account_card_id objectid
billing.address1 string
billing.address2 string
billing.card object
billing.card.address_check string
billing.card.brand string
billing.card.cvc_check string
billing.card.exp_month int
billing.card.exp_year int
billing.card.gateway string
billing.card.last4 string
billing.card.test bool
billing.card.token string Required
billing.card.zip_check string
billing.city string
billing.country string
billing.default bool
billing.first_name string
billing.last_name string
billing.method string
billing.name string
billing.phone string Format (phone)
billing.state string
billing.zip string
comments string
conversion_add bool
conversion_checkout bool
coupon link → /coupons/{coupon_id}
coupon_code string
coupon_id objectid
currency string
date_abandoned
Date the cart should be marked as abandoned
date
date_created date Auto
date_updated date Auto (update)
discount_total currency Formula item_discount
discounts array
discounts.amount currency
discounts.id string Primary
discounts.rule object
discounts.type string
download_delivery bool Read-only
draft bool
grand_total currency Formula sub_total + shipment_total + tax_included_total - (discount_total)
guest bool Formula if(order_id, guest, if(not(account.password), true, false))
id objectid Primary
item_discount currency Formula sum(items.discount_total)
item_quantity int Formula sum(items.quantity)
item_shipment_weight float Formula sum(items.shipment_weight)
item_tax currency Formula sum(items.tax_total)
item_tax_included bool
items array
items.bundle_items array
items.bundle_items.delivery string Immutable
Enumerated (shipment, download)
Default
items.bundle_items.id objectid Primary
items.bundle_items.product link → /products/{product_id}
items.bundle_items.product_id objectid Required
items.bundle_items.quantity int Default
items.bundle_items.quantity_total int
items.bundle_items.shipment_weight float
items.bundle_items.variant link → /products:variants/{variant_id}
items.bundle_items.variant_id objectid
items.delivery string Immutable
Enumerated (shipment, download)
Default
items.discount_each currency Formula discount_total / quantity
items.discount_total currency Formula sum(discounts.amount)
items.discounts array
items.discounts.amount currency
items.discounts.id string Primary
items.id objectid Primary
Auto
Immutable
items.options array
items.options.id string Primary
items.options.name string
items.options.price currency
items.options.shipment_weight float
items.options.value string
items.options.variant bool
items.orig_price currency
items.price currency Default
items.price_total currency Formula price * quantity
items.product link → /products/{product_id}
items.product_id objectid Required
Immutable
items.quantity int Default
items.shipment_weight float
items.tax_each currency Formula tax_total / quantity
items.tax_total currency Formula sum(taxes.amount)
items.taxes array
items.taxes.amount currency
items.taxes.id string Primary
items.variant link → /products:variants/{variant_id}
items.variant_id objectid Immutable
notes string
number string Name
Auto
Immutable
order link → /orders/{order_id}
order_id objectid
promotion_ids array
promotions link → /promotions/{promotion_ids}
recovered bool
schedule object
schedule.interval string Enumerated (monthly, daily, weekly, yearly)
schedule.interval_count int
shipment_delivery bool Read-only
shipment_discount currency
shipment_price currency Formula shipping.price
shipment_rating object
shipment_rating.date_created date Auto
shipment_rating.errors array
shipment_rating.errors.code string
shipment_rating.errors.message string
shipment_rating.md5 string
shipment_rating.services array
shipment_rating.services.carrier string
shipment_rating.services.id string Primary
shipment_rating.services.name string
shipment_rating.services.price currency
shipment_tax currency
shipment_tax_included bool
shipment_total currency Formula shipment_price - shipment_discount
shipping object
shipping.account_address link → /accounts:addresses/{account_address_id}
shipping.account_address_id objectid
shipping.address1 string
shipping.address2 string
shipping.city string
shipping.country string
shipping.default bool
shipping.first_name string
shipping.last_name string
shipping.name string
shipping.phone string
shipping.price currency
shipping.service string
shipping.service_name string
shipping.state string
shipping.zip string
status string Auto
Read-only
Enumerated (active, converted, abandoned)
Default
sub_total currency Formula sum(items.price_total)
tax_included_total currency Formula if(item_tax_included, 0, item_tax) + if(shipment_tax_included, 0, shipment_tax)
tax_total currency Formula item_tax + shipment_tax
taxes array
taxes.amount currency
taxes.id string Primary
taxes.name string
taxes.priority int
taxes.rate float
taxes.shipping bool

Categories

Organize products into categories for customer navigation.

// Create a category
$result = $client->post('/categories', array(
    'name' => '<category name>',
    'description' => '<category description>',
    'active' => true,
    ...
));

// Retrieve a category
$result = $client->get('/categories/{id}', array(
    'id' => '<category id>',
    ...
));

// Update a category
$result = $client->put('/categories/{id}', array(
    'id' => '<category id>',
    ...
));

// Delete a category
$result = $client->delete('/categories/{id}', array(
    'id' => '<category id>'
));
// Create a category
client.post('/categories', { 
    name: '<category name>',
    description: '<category description>',
    active: '<category active>',
    ...
}, function(result) {
    ...
});

// Retrieve a category
client.get('/categories/{id}', { id: '<category id>', ... }, function(result) {
    ...
});

// Update a category
client.put('/categories/{id}', { id: '<category id>', ... }, function(result) {
    ...
});

// Delete a category
client.delete('/categories/{id}', { id: '<category id>' }, function(result) {
    ...
});
# Create a category
curl -X POST https://api.schema.io/categories \ 
    -d 'name=<category name>' \ 
    -d 'description=<category description>' \ 
    -d 'active=<category active>' \ 

# Retrieve a category
curl -G https://api.schema.io/categories/{id} \
    -d 'id=<category id>' \

# Update a category
curl -X PUT https://api.schema.io/categories/{id} \
    -d 'id=<category id>' \

# Delete a category
curl -X DELETE https://api.schema.io/categories/{id} \
    -d 'id=<category id>' \
Category Fields
active
Indicates when a category is active
bool
children link → /categories?parent_id=id
date_created date Auto
date_updated date Auto (update)
description string
id objectid Primary
image object
image.caption string
image.file file
image.file.content_type string
image.file.data filedata
image.file.date_uploaded date
image.file.filename string
image.file.height int
image.file.id objectid Primary
image.file.length int
image.file.md5 string
image.file.metadata object
image.file.url string
image.file.width int
image.name string Name
images array
images.caption string
images.file file
images.file.content_type string
images.file.data filedata
images.file.date_uploaded date
images.file.filename string
images.file.height int
images.file.id objectid Primary
images.file.length int
images.file.md5 string
images.file.metadata object
images.file.url string
images.file.width int
images.name string Name
meta_description string
meta_keywords string
name string Name
Required
navigation
Indicates when a category should be used in site navigation
bool
parent link → /categories/{parent_id}
parent_id objectid
products collection
products.date_created date Auto
products.date_updated date Auto (update)
products.id objectid Primary
products.parent link → /categories/{parent_id}
products.parent_id objectid Required
Immutable
products.product link → /products/{product_id}
products.product_id objectid Required
Immutable
products.sort
Number used to sort products within a parent category
int
products_indexed
Products indexed by this category and ordered by their respective sort value
link → /products?sort=category_index.sort.{id}+asc?category_index.id=id
slug
URL friendly identifier
string Default
sort
Number used to sort a category at root level or within a parent category
int
top
Top level parent of a category
link → /categories/{top_id}
top_id objectid Formula if(and(parent_id, parent.top_id), parent.top_id, parent_id)

Contacts

// Create a contact
$result = $client->post('/contacts', array(
    'name' => '<contact name>',
    ...
));

// Retrieve a contact
$result = $client->get('/contacts/{id}', array(
    'id' => '<contact id>',
    ...
));

// Update a contact
$result = $client->put('/contacts/{id}', array(
    'id' => '<contact id>',
    ...
));

// Delete a contact
$result = $client->delete('/contacts/{id}', array(
    'id' => '<contact id>'
));
// Create a contact
client.post('/contacts', { 
    name: '<contact name>',
    ...
}, function(result) {
    ...
});

// Retrieve a contact
client.get('/contacts/{id}', { id: '<contact id>', ... }, function(result) {
    ...
});

// Update a contact
client.put('/contacts/{id}', { id: '<contact id>', ... }, function(result) {
    ...
});

// Delete a contact
client.delete('/contacts/{id}', { id: '<contact id>' }, function(result) {
    ...
});
# Create a contact
curl -X POST https://api.schema.io/contacts \ 
    -d 'name=<contact name>' \ 

# Retrieve a contact
curl -G https://api.schema.io/contacts/{id} \
    -d 'id=<contact id>' \

# Update a contact
curl -X PUT https://api.schema.io/contacts/{id} \
    -d 'id=<contact id>' \

# Delete a contact
curl -X DELETE https://api.schema.io/contacts/{id} \
    -d 'id=<contact id>' \
Contact Fields
account link → /accounts/{account_id}
account_id objectid
address1 string
address2 string
alt_email string Format (email)
birthdate date
city string
country string
date_created date Auto
date_updated date Auto (update)
department string
email string Format (email)
email_optin bool
email_optin_lists object
email_optin_lists.* bool
first_name string
id objectid Primary
last_name string
name string Name
Read-only
Formula if(salutation, salutation.label+' ', '') + if(first_name, first_name+' '+last_name, last_name)
notes string
other_phone string Format (phone)
phone string Format (phone)
phone_optin bool
salutation string Enumerated (, mr, ms, mrs, dr, prof)
state string
title string
zip string

Coupons

Create discount vouchers for marketing promotions.

// Create a coupon
$result = $client->post('/coupons', array(
    'name' => '<coupon name>',
    'codes' => '<coupon codes>',
    'discounts' => '<coupon discount rules>',
    'active' => true,
    ...
));

// Retrieve a coupon
$result = $client->get('/coupons/{id}', array(
    'id' => '<coupon id>',
    ...
));

// Update a coupon
$result = $client->put('/coupons/{id}', array(
    'id' => '<coupon id>',
    ...
));

// Delete a coupon
$result = $client->delete('/coupons/{id}', array(
    'id' => '<coupon id>'
));
// Create a coupon
client.post('/coupons', { 
    name: '<coupon name>',
    codes: '<coupon codes>',
    discounts: '<coupon discounts>',
    active: '<coupon active>',
    ...
}, function(result) {
    ...
});

// Retrieve a coupon
client.get('/coupons/{id}', { id: '<coupon id>', ... }, function(result) {
    ...
});

// Update a coupon
client.put('/coupons/{id}', { id: '<coupon id>', ... }, function(result) {
    ...
});

// Delete a coupon
client.delete('/coupons/{id}', { id: '<coupon id>' }, function(result) {
    ...
});
# Create a coupon
curl -X POST https://api.schema.io/coupons \ 
    -d 'name=<coupon name>' \ 
    -d 'codes=<coupon codes>' \ 
    -d 'discounts=<coupon discounts>' \ 
    -d 'active=<coupon active>' \ 

# Retrieve a coupon
curl -G https://api.schema.io/coupons/{id} \
    -d 'id=<coupon id>' \

# Update a coupon
curl -X PUT https://api.schema.io/coupons/{id} \
    -d 'id=<coupon id>' \

# Delete a coupon
curl -X DELETE https://api.schema.io/coupons/{id} \
    -d 'id=<coupon id>' \
Coupon Fields
active bool
active_generations link → /coupons:generations?parent_id=id?complete=0
codes collection
codes.code
Unique code used to identify the coupon
string Auto
Format (uppercase)
codes.date_created date Auto
codes.date_updated date Auto (update)
codes.gen_id
Generation identifier if generated automatically
objectid
codes.id objectid Primary
codes.orders link → /orders?coupon_code=code
codes.parent link → /coupons/{parent_id}
codes.parent_id objectid Required
Immutable
codes.subscriptions link → /subscriptions?coupon_code=code
codes.use_count
Number of times a code has been used
int Formula use_total
codes.use_total
This field is deprecated in favor of use_count
int
currency string
date_created date Auto
date_expired
Date the coupon is considered expired and no longer available for use
date
date_updated date Auto (update)
date_valid
Date the coupon is first available for use
date
description string
discount_group
Group of discounts for which one exclusive set of rules can apply at a time
string
discounts
Discount rules used when the coupon is applied
array
discounts.category link → /categories/{category_id}
discounts.category_id
Category identifier for which a rule will apply
objectid
discounts.price_min
Minimum product price required for a rule to apply
currency
discounts.product link → /products/{product_id}
discounts.product_id
Product identifier for which a rule will apply
objectid
discounts.quantity_add
Product quantity to add to an order if applicable
int
discounts.quantity_max
Maximum product quantity for which a rule will apply
int
discounts.quantity_min
Minimum product quantity required for a rule to apply
int
discounts.shipment_service
Shipment service to apply discount if applicable
string
discounts.total_min
Minimum order total required for a rule to apply
currency
discounts.type
Type of discount to apply
string Enumerated (total, shipment, product, category)
Default
discounts.value
Fixed value of discount (deprecated)
currency
discounts.value_fixed
Fixed value of discount
currency
discounts.value_percent
Percentage value of discount
float
discounts.value_type
Type of value to calculate discount amount
string Required
Enumerated (fixed, percent)
Default
discounts.variant link → /products:variants/{variant_id}
discounts.variant_id
Variant identifier for which a rule will apply
objectid
generations collection
generations.codes link → /coupons:codes?gen_id=id
generations.complete
Indicates when code generation is complete
bool
generations.count
Number of codes to generate
int Required
Immutable
generations.date_created date Auto
generations.date_updated date Auto (update)
generations.error
Message returned by code generation process if an error occurs
string
generations.id objectid Primary
generations.parent link → /coupons/{parent_id}
generations.parent_id objectid Required
Immutable
generations.pattern
Custom code pattern used to generate new codes
string
generations.pattern_type
Pattern type used to generate codes
string Enumerated (default, custom)
Default
id objectid Primary
limit_account_groups
Account groups that may apply the coupon
array
limit_account_segments
Account segments that may apply the coupon
array
limit_account_uses
Maximum number of times the coupon may be used by each account
int
limit_code_uses
Maximum number of times the coupon code may be used
int
limit_uses
Maximum number of times the coupon may be applied
int
multi_codes
Indicates when the coupon is identified by multiple coupon codes
bool
name string Name
Required
orders link → /orders?coupon_id=id
subscriptions link → /subscriptions?coupon_id=id
use_count
Number of times the coupon has been used
int Formula use_total
use_total
This field is deprecated in favor of use_count
int
uses collection
uses.account_id objectid Immutable
uses.code string Required
Immutable
uses.code_id objectid Required
Immutable
uses.date_created date Auto
uses.date_updated date Auto (update)
uses.id objectid Primary
uses.order link → /orders/{order_id}
uses.order_id objectid Immutable
uses.parent link → /coupons/{parent_id}
uses.parent_id objectid Required
Immutable
uses.subscription link → /subscriptions/{subscription_id}
uses.subscription_id objectid Immutable

Credit Memos

Track credits and refund payments.

// Create a credit
$result = $client->post('/credits', array(
    'account_id' => '<credit account_id>',
    'items' => '<credit items>',
    'extra_credit' => '<extra credit amount>',
    'restock_fee' => '<restock fee amount>',
    ...
));

// Retrieve a credit
$result = $client->get('/credits/{id}', array(
    'id' => '<credit id>',
    ...
));

// Update a credit
$result = $client->put('/credits/{id}', array(
    'id' => '<credit id>',
    ...
));

// Delete a credit
$result = $client->delete('/credits/{id}', array(
    'id' => '<credit id>'
));
// Create a credit
client.post('/credits', { 
    account_id: '<credit account_id>',
    items: '<credit items>',
    extra_credit: '<credit extra_credit>',
    restock_fee: '<credit restock_fee>',
    ...
}, function(result) {
    ...
});

// Retrieve a credit
client.get('/credits/{id}', { id: '<credit id>', ... }, function(result) {
    ...
});

// Update a credit
client.put('/credits/{id}', { id: '<credit id>', ... }, function(result) {
    ...
});

// Delete a credit
client.delete('/credits/{id}', { id: '<credit id>' }, function(result) {
    ...
});
# Create a credit
curl -X POST https://api.schema.io/credits \ 
    -d 'account_id=<credit account_id>' \ 
    -d 'items=<credit items>' \ 
    -d 'extra_credit=<credit extra_credit>' \ 
    -d 'restock_fee=<credit restock_fee>' \ 

# Retrieve a credit
curl -G https://api.schema.io/credits/{id} \
    -d 'id=<credit id>' \

# Update a credit
curl -X PUT https://api.schema.io/credits/{id} \
    -d 'id=<credit id>' \

# Delete a credit
curl -X DELETE https://api.schema.io/credits/{id} \
    -d 'id=<credit id>' \
Credit Memo Fields
account link → /accounts/{account_id}
account_id objectid Required
Immutable
Default
currency string
date_created date Auto
date_period_end date Default
date_period_start date Default
date_updated date Auto (update)
discount_total currency Formula item_discount
extra_credit
Extra credit amount in addition to item and shipping amounts
currency
grand_total currency Formula sub_total + shipment_total + tax_included_total + extra_credit - (restock_fee) - (discount_total)
id objectid Primary
invoice link → /invoices/{invoice_id}
invoice_id objectid Immutable
item_discount currency Formula sum(items.discount_total)
item_quantity int Formula sum(items.quantity)
item_tax currency Formula sum(items.tax_total)
item_tax_included bool
items array
items.bundle_items array Immutable
items.bundle_items.id objectid Primary
items.bundle_items.product link → /products/{product_id}
items.bundle_items.product_id objectid
items.bundle_items.quantity int
items.bundle_items.quantity_total int
items.bundle_items.variant link → /products:variants/{variant_id}
items.bundle_items.variant_id objectid
items.description string
items.discount_each currency Immutable
items.discount_total currency Immutable
items.id objectid Primary
Immutable
items.options array Immutable
items.options.id string Primary
items.options.name string
items.options.value string
items.price currency Immutable
items.price_total currency Formula price * quantity
items.product link → /products/{product_id}
items.product_id objectid Immutable
items.quantity int Default
items.restock bool
items.tax_each currency Immutable
items.tax_total currency Immutable
items.variant link → /products:variants/{variant_id}
items.variant_id objectid Immutable
notes string
notified bool
number string Name
Auto
Immutable
order link → /orders/{order_id}
order_id objectid Immutable
refund_due currency Formula if(and(not(void), or(not(order_id), not(invoice_id))), grand_total - refund_total, 0)
refund_total currency Read-only
refunded bool Read-only
Formula if(refund_due <= 0, true, false)
refunds link → /payments:refunds?credit_id=id
restock_fee
Amount to subtract from a credit for restocking purposes
currency
shipment_tax currency Immutable
shipment_tax_included bool
shipment_tax_included_total currency Formula shipment_total + if(shipment_tax_included, 0, shipment_tax)
shipment_total currency Immutable
source link → /{source_model}/{source_id}
source_id objectid Read-only
Formula or(order_id, subscription_id)
source_model string Read-only
Formula if(order_id, 'orders', if(subscription_id, 'subscriptions'))
status string Auto
Read-only
Enumerated (pending, void, refunded)
Default
sub_total currency Formula sum(items.price_total)
subscription link → /subscriptions/{subscription_id}
subscription_id objectid Immutable
tax_included_total currency Formula if(item_tax_included, 0, item_tax) + if(shipment_tax_included, 0, shipment_tax)
tax_total currency Formula item_tax + shipment_tax
void bool Immutable

Events

// Create an event
$result = $client->post('/events', array(
    'model' => '<event model>',
    'type' => '<event type>',
    ...
));

// Retrieve an event
$result = $client->get('/events/{id}', array(
    'id' => '<event id>',
    ...
));

// Update an event
$result = $client->put('/events/{id}', array(
    'id' => '<event id>',
    ...
));

// Delete an event
$result = $client->delete('/events/{id}', array(
    'id' => '<event id>'
));
// Create an event
client.post('/events', { 
    model: '<event model>',
    type: '<event type>',
    ...
}, function(result) {
    ...
});

// Retrieve an event
client.get('/events/{id}', { id: '<event id>', ... }, function(result) {
    ...
});

// Update an event
client.put('/events/{id}', { id: '<event id>', ... }, function(result) {
    ...
});

// Delete an event
client.delete('/events/{id}', { id: '<event id>' }, function(result) {
    ...
});
# Create an event
curl -X POST https://api.schema.io/events \ 
    -d 'model=<event model>' \ 
    -d 'type=<event type>' \ 

# Retrieve an event
curl -G https://api.schema.io/events/{id} \
    -d 'id=<event id>' \

# Update an event
curl -X PUT https://api.schema.io/events/{id} \
    -d 'id=<event id>' \

# Delete an event
curl -X DELETE https://api.schema.io/events/{id} \
    -d 'id=<event id>' \
Event Fields
data
Event record data
object
data.id objectid Primary
date_created date Auto
date_updated date Auto (update)
id objectid Primary
model
Model name
string Required
type
Event type
string Required
user_id
Admin user identifier if applicable to the event action
objectid
webhooks
Webhooks triggered by the event
collection
webhooks.attempts int
webhooks.date_retry
Date the webhook request should be retried
date
webhooks.date_sent
Date the webhook request was sent
date
webhooks.id objectid Primary
webhooks.parent link → /events/{parent_id}
webhooks.parent_id objectid Required
Immutable
webhooks.pending bool Read-only
Formula if(or(not(date_sent), date_retry), true, false)
webhooks.response string
webhooks.status int
webhooks.webhook_id
Webhook configuraton identifier
objectid Required
webhooks_pending
Number of webhooks pending receipt
int

Invoices

Track requests for payment from orders and subscriptions.

// Create an invoice
$result = $client->post('/invoices', array(
    'account_id' => '<invoice account_id>',
    'items' => '<invoice items>',
    ...
));

// Retrieve an invoice
$result = $client->get('/invoices/{id}', array(
    'id' => '<invoice id>',
    ...
));

// Update an invoice
$result = $client->put('/invoices/{id}', array(
    'id' => '<invoice id>',
    ...
));

// Delete an invoice
$result = $client->delete('/invoices/{id}', array(
    'id' => '<invoice id>'
));
// Create an invoice
client.post('/invoices', { 
    account_id: '<invoice account_id>',
    items: '<invoice items>',
    ...
}, function(result) {
    ...
});

// Retrieve an invoice
client.get('/invoices/{id}', { id: '<invoice id>', ... }, function(result) {
    ...
});

// Update an invoice
client.put('/invoices/{id}', { id: '<invoice id>', ... }, function(result) {
    ...
});

// Delete an invoice
client.delete('/invoices/{id}', { id: '<invoice id>' }, function(result) {
    ...
});
# Create an invoice
curl -X POST https://api.schema.io/invoices \ 
    -d 'account_id=<invoice account_id>' \ 
    -d 'items=<invoice items>' \ 

# Retrieve an invoice
curl -G https://api.schema.io/invoices/{id} \
    -d 'id=<invoice id>' \

# Update an invoice
curl -X PUT https://api.schema.io/invoices/{id} \
    -d 'id=<invoice id>' \

# Delete an invoice
curl -X DELETE https://api.schema.io/invoices/{id} \
    -d 'id=<invoice id>' \
Invoice Fields
account link → /accounts/{account_id}
account_id objectid Required
Immutable
Default
closed bool
credit_total currency Read-only
credits link → /credits?invoice_id=id
currency string Immutable
date_created date Auto
date_due date
date_payment_retry date
date_period_end date Default
date_period_start date Default
date_updated date Auto (update)
discount_total currency Formula item_discount
grand_total currency Formula sub_total + tax_included_total + shipment_total - (discount_total)
id objectid Primary
item_discount currency Formula sum(items.discount_total)
item_quantity int Formula sum(items.quantity)
item_quantity_creditable int Formula sum(items.quantity_creditable)
item_tax currency Formula sum(items.tax_total)
item_tax_included bool
items array
items.bundle_items array Immutable
items.bundle_items.id objectid Primary
items.bundle_items.product link → /products/{product_id}
items.bundle_items.product_id objectid
items.bundle_items.quantity int
items.bundle_items.quantity_total int
items.bundle_items.variant link → /products:variants/{variant_id}
items.bundle_items.variant_id objectid
items.description string
items.discount_each currency Immutable
items.discount_total currency Immutable
items.id objectid Primary
Auto
Immutable
items.options array Immutable
items.options.id string Primary
items.options.name string
items.options.value string
items.price currency Immutable
items.price_total currency Formula price * quantity
items.product link → /products/{product_id}
items.product_id objectid Immutable
items.quantity int Default
items.quantity_creditable int Formula if(price > 0, quantity - quantity_credited, 0)
items.quantity_credited int
items.tax_each currency Immutable
items.tax_total currency Immutable
items.variant link → /products:variants/{variant_id}
items.variant_id objectid Immutable
net_days int
notes string
number string Name
Auto
Immutable
order link → /orders/{order_id}
order_id objectid Immutable
paid bool Read-only
Formula if(payment_due <= 0, true, false)
pastdue bool Read-only
payment_due currency Formula if(not(void), grand_total - credit_total - payment_total, 0)
payment_error string
payment_retry_count int
payment_retry_resolve int
payment_total currency Read-only
payments link → /payments?invoice_id=id
refunds link → /payments:refunds?invoice_id=id
shipment_tax currency Immutable
shipment_tax_included bool
shipment_tax_included_total currency Formula shipment_total + if(shipment_tax_included, 0, shipment_tax)
shipment_total currency Immutable
source link → /{source_model}/{source_id}
source_id objectid Read-only
Formula or(order_id, subscription_id)
source_model string Read-only
Formula if(order_id, 'orders', if(subscription_id, 'subscriptions'))
status string Auto
Read-only
Enumerated (pending, void, paid, unpaid)
Default
sub_total currency Formula sum(items.price_total)
subscription link → /subscriptions/{subscription_id}
subscription_id objectid Immutable
tax_included_total currency Formula if(item_tax_included, 0, item_tax) + if(shipment_tax_included, 0, shipment_tax)
tax_total currency Formula item_tax + shipment_tax
void bool Immutable

Notifications

Send notifications such as order receipts and admin updates.

// Create a notification
$result = $client->post('/notifications', array(
    'record_id' => '<related record id>',
    'template' => '<notification template>',
    'contact' => 'customer@example.com',
    ...
));

// Retrieve a notification
$result = $client->get('/notifications/{id}', array(
    'id' => '<notification id>',
    ...
));

// Update a notification
$result = $client->put('/notifications/{id}', array(
    'id' => '<notification id>',
    ...
));

// Delete a notification
$result = $client->delete('/notifications/{id}', array(
    'id' => '<notification id>'
));
// Create a notification
client.post('/notifications', { 
    record_id: '<notification record_id>',
    template: '<notification template>',
    contact: '<notification contact>',
    ...
}, function(result) {
    ...
});

// Retrieve a notification
client.get('/notifications/{id}', { id: '<notification id>', ... }, function(result) {
    ...
});

// Update a notification
client.put('/notifications/{id}', { id: '<notification id>', ... }, function(result) {
    ...
});

// Delete a notification
client.delete('/notifications/{id}', { id: '<notification id>' }, function(result) {
    ...
});
# Create a notification
curl -X POST https://api.schema.io/notifications \ 
    -d 'record_id=<notification record_id>' \ 
    -d 'template=<notification template>' \ 
    -d 'contact=<notification contact>' \ 

# Retrieve a notification
curl -G https://api.schema.io/notifications/{id} \
    -d 'id=<notification id>' \

# Update a notification
curl -X PUT https://api.schema.io/notifications/{id} \
    -d 'id=<notification id>' \

# Delete a notification
curl -X DELETE https://api.schema.io/notifications/{id} \
    -d 'id=<notification id>' \
Notification Fields
config link → /:notifications/{template}
contact
Notification contact address if applicable
string
date_created date Auto
date_updated date Auto (update)
error
Error message returned by sending process if applicable
string
id objectid Primary
record link → /{config.model}/{record_id}
record_id
Record ID of the collection for which the notification template is defined
string Required
template
Notification template name
string Required

Orders

Track requests for purchase from customers.

// Create an order
$result = $client->post('/orders', array(
    'account_id' => '<order account_id>',
    'items' => '<order items>',
    'billing' => '<order billing>',
    'shipping' => '<order shipping>',
    'notes' => '<order shipping>',
    ...
));

// Retrieve an order
$result = $client->get('/orders/{id}', array(
    'id' => '<order id>',
    ...
));

// Update an order
$result = $client->put('/orders/{id}', array(
    'id' => '<order id>',
    ...
));

// Delete an order
$result = $client->delete('/orders/{id}', array(
    'id' => '<order id>'
));
// Create an order
client.post('/orders', { 
    account_id: '<order account_id>',
    items: '<order items>',
    billing: '<order billing>',
    shipping: '<order shipping>',
    notes: '<order notes>',
    ...
}, function(result) {
    ...
});

// Retrieve an order
client.get('/orders/{id}', { id: '<order id>', ... }, function(result) {
    ...
});

// Update an order
client.put('/orders/{id}', { id: '<order id>', ... }, function(result) {
    ...
});

// Delete an order
client.delete('/orders/{id}', { id: '<order id>' }, function(result) {
    ...
});
# Create an order
curl -X POST https://api.schema.io/orders \ 
    -d 'account_id=<order account_id>' \ 
    -d 'items=<order items>' \ 
    -d 'billing=<order billing>' \ 
    -d 'shipping=<order shipping>' \ 
    -d 'notes=<order notes>' \ 

# Retrieve an order
curl -G https://api.schema.io/orders/{id} \
    -d 'id=<order id>' \

# Update an order
curl -X PUT https://api.schema.io/orders/{id} \
    -d 'id=<order id>' \

# Delete an order
curl -X DELETE https://api.schema.io/orders/{id} \
    -d 'id=<order id>' \
Order Fields
account link → /accounts/{account_id}
account_credit_amount
Amount of account credit to spend for automatic payment
currency
account_id objectid Required
Immutable
authorized_payment link → /payments/{authorized_payment_id}
authorized_payment_id string
billing object
billing.account_card link → /accounts:cards/{account_card_id}
billing.account_card_id objectid
billing.address1 string
billing.address2 string
billing.card object
billing.card.address_check string
billing.card.brand string
billing.card.cvc_check string
billing.card.exp_month int
billing.card.exp_year int
billing.card.gateway string
billing.card.last4 string
billing.card.test bool
billing.card.token string Required
billing.card.zip_check string
billing.city string
billing.country string
billing.default bool
billing.first_name string
billing.last_name string
billing.method string
billing.name string
billing.phone string Format (phone)
billing.state string
billing.zip string
canceled bool Immutable
cart link → /carts/{cart_id}
cart_id objectid Immutable
closed bool
comments string
coupon link → /coupons/{coupon_id}
coupon_code string
coupon_id objectid
credit_total currency Read-only
credits link → /credits?order_id=id
currency string Immutable
date_created date Auto
date_scheduled date Read-only
Formula date_next_interval(interval, date_created, interval_count)
date_updated date Auto (update)
delivered bool Read-only
Formula if(and(not(draft), or(delivery_marked, and(item_quantity_delivered > 0, item_quantity_deliverable <= 0))), true, false)
delivery_marked bool
discount_total currency Formula item_discount
discounts array
discounts.amount currency
discounts.id string Primary
discounts.rule object
discounts.type string
download_delivery
Indicates an order contains at least one item to be delivered by Download
bool Read-only
downloads link → /downloads?order_id=id
draft bool
grand_total currency Formula sub_total + shipment_total + tax_included_total - (discount_total)
guest bool Default
hold bool
id objectid Primary
invoices link → /invoices?order_id=id
item_discount currency Formula sum(items.discount_total)
item_quantity int Formula sum(items.quantity)
item_quantity_canceled int Formula sum(items.quantity_canceled)
item_quantity_creditable int Formula sum(items.quantity_creditable)
item_quantity_credited int Formula sum(items.quantity_credited)
item_quantity_deliverable int Formula sum(items.quantity_deliverable)
item_quantity_delivered int Formula sum(items.quantity_delivered)
item_quantity_download_deliverable int Formula if(download_delivery, sum(items.quantity_download_deliverable))
item_quantity_invoiceable int Formula sum(items.quantity_invoiceable)
item_quantity_invoiced int Formula sum(items.quantity_invoiced)
item_quantity_shipment_deliverable int Formula if(shipment_delivery, sum(items.quantity_shipment_deliverable))
item_shipment_weight float Formula sum(items.shipment_weight)
item_tax currency Formula sum(items.tax_total)
item_tax_included bool
items array
items.bundle_items array
items.bundle_items.delivery string Immutable
Enumerated (shipment, download)
Default
items.bundle_items.id objectid Primary
items.bundle_items.product link → /products/{product_id}
items.bundle_items.product_id objectid Required
items.bundle_items.quantity int Default
items.bundle_items.quantity_canceled int
items.bundle_items.quantity_consumed int
items.bundle_items.quantity_deliverable int Formula if(delivery, quantity_total - quantity_delivered - quantity_canceled, 0)
items.bundle_items.quantity_delivered int
items.bundle_items.quantity_download_deliverable int Formula if(delivery == 'download', quantity - quantity_delivered - quantity_credited - quantity_canceled)
items.bundle_items.quantity_returned int
items.bundle_items.quantity_shipment_deliverable int Formula if(delivery == 'shipment', quantity - quantity_delivered - quantity_credited - quantity_canceled)
items.bundle_items.quantity_total int
items.bundle_items.shipment_weight float
items.bundle_items.variant link → /products:variants/{variant_id}
items.bundle_items.variant_id objectid
items.delivery string Immutable
Enumerated (shipment, download)
Default
items.discount_each currency Formula discount_total / quantity
items.discount_total currency Formula sum(discounts.amount)
items.discounts array
items.discounts.amount currency
items.discounts.id string Primary
items.id objectid Primary
Auto
Immutable
items.options array
items.options.id string Primary
items.options.name string
items.options.price currency
items.options.shipment_weight float
items.options.value string
items.options.variant bool
items.orig_price currency
items.price currency Default
items.price_total currency Formula price * quantity
items.product link → /products/{product_id}
items.product_id objectid Required
Immutable
items.quantity int Default
items.quantity_canceled int
items.quantity_consumed int
items.quantity_creditable int Formula if((price_total - discount_total > 0), quantity - quantity_credited, 0)
items.quantity_credited int
items.quantity_deliverable int Formula if(or(delivery, sum(bundle_items.quantity_deliverable)), quantity - quantity_delivered - quantity_credited - quantity_canceled, 0)
items.quantity_delivered int
items.quantity_download_deliverable int Formula if(or(delivery == 'download', sum(bundle_items.quantity_download_deliverable)), quantity - quantity_delivered - quantity_credited - quantity_canceled)
items.quantity_invoiceable int Formula if((price_total - discount_total > 0), quantity - quantity_invoiced - quantity_canceled, 0)
items.quantity_invoiced int
items.quantity_returned int
items.quantity_shipment_deliverable int Formula if(or(delivery == 'shipment', sum(bundle_items.quantity_shipment_deliverable)), quantity - quantity_delivered - quantity_credited - quantity_canceled)
items.shipment_weight float
items.tax_each currency Formula tax_total / quantity
items.tax_total currency Formula sum(taxes.amount)
items.taxes array
items.taxes.amount currency
items.taxes.id string Primary
items.variant link → /products:variants/{variant_id}
items.variant_id objectid Immutable
next link → /orders/{next_id}
next_id objectid Immutable
notes string
notifications link → /notifications?record_id=id
number string Name
Auto
Immutable
paid bool Read-only
Formula if(and(not(draft), not(canceled), or(payment_marked, and(payment_total > 0, payment_balance >= 0))), true, false)
parent link → /orders/{parent_id}
parent_id objectid Immutable
payment_balance currency Formula payment_total - refund_total - grand_total + (credit_total)
payment_marked bool
payment_total currency Read-only
payments link → /payments?order_id=id
pending_credits link → /credits?order_id=id?status=pending
pending_invoices link → /invoices?order_id=id?status=pending
prev link → /orders/{prev_id}
prev_id objectid Immutable
promotion_ids array
promotions link → /promotions/{promotion_ids}
refund_marked bool
refund_total currency Read-only
refunded bool Read-only
Formula if(and(not(draft), refund_total > 0, or(refund_marked, refund_total == payment_total)), true, false)
refunds link → /payments:refunds?order_id=id
schedule object
schedule.interval string Enumerated (monthly, daily, weekly, yearly)
schedule.interval_count int
shipment_delivery
Indicates an order contains at least one item to be delivered by Shipment
bool Read-only
shipment_discount currency
shipment_price currency Formula shipping.price
shipment_rating object
shipment_rating.date_created date Auto
shipment_rating.errors array
shipment_rating.errors.code string
shipment_rating.errors.message string
shipment_rating.fingerprint string
shipment_rating.services array
shipment_rating.services.carrier string
shipment_rating.services.id string Primary
shipment_rating.services.name string
shipment_rating.services.price currency
shipment_tax currency
shipment_tax_included bool
shipment_tax_included_total currency Formula shipment_total + if(shipment_tax_included, 0, shipment_tax)
shipment_total currency Formula shipment_price - shipment_discount
shipment_total_credited currency Read-only
shipment_total_invoiced currency Read-only
shipments link → /shipments?order_id=id
shipping object
shipping.account_address link → /accounts:addresses/{account_address_id}
shipping.account_address_id objectid
shipping.address1 string
shipping.address2 string
shipping.city string
shipping.country string
shipping.default bool
shipping.first_name string
shipping.last_name string
shipping.name string
shipping.phone string
shipping.price currency
shipping.service string
shipping.service_name string
shipping.state string
shipping.zip string
status string Auto
Read-only
Enumerated (pending, draft, payment_pending, delivery_pending, hold, complete, canceled)
Default
sub_total currency Formula sum(items.price_total)
tax_included_total currency Formula if(item_tax_included, 0, item_tax) + if(shipment_tax_included, 0, shipment_tax)
tax_total currency Formula item_tax + shipment_tax
taxes array
taxes.amount currency
taxes.id string Primary
taxes.name string
taxes.priority int
taxes.rate float
taxes.shipping bool

Pages

Organize web site content into pages for customers.

// Create a page
$result = $client->post('/pages', array(
    'name' => '<page name>',
    'description' => '<page description>',
    'keywords' => '<page keywords>',
    'content' => '<page content>',
    ...
));

// Retrieve a page
$result = $client->get('/pages/{id}', array(
    'id' => '<page id>',
    ...
));

// Update a page
$result = $client->put('/pages/{id}', array(
    'id' => '<page id>',
    ...
));

// Delete a page
$result = $client->delete('/pages/{id}', array(
    'id' => '<page id>'
));
// Create a page
client.post('/pages', { 
    name: '<page name>',
    description: '<page description>',
    keywords: '<page keywords>',
    content: '<page content>',
    ...
}, function(result) {
    ...
});

// Retrieve a page
client.get('/pages/{id}', { id: '<page id>', ... }, function(result) {
    ...
});

// Update a page
client.put('/pages/{id}', { id: '<page id>', ... }, function(result) {
    ...
});

// Delete a page
client.delete('/pages/{id}', { id: '<page id>' }, function(result) {
    ...
});
# Create a page
curl -X POST https://api.schema.io/pages \ 
    -d 'name=<page name>' \ 
    -d 'description=<page description>' \ 
    -d 'keywords=<page keywords>' \ 
    -d 'content=<page content>' \ 

# Retrieve a page
curl -G https://api.schema.io/pages/{id} \
    -d 'id=<page id>' \

# Update a page
curl -X PUT https://api.schema.io/pages/{id} \
    -d 'id=<page id>' \

# Delete a page
curl -X DELETE https://api.schema.io/pages/{id} \
    -d 'id=<page id>' \
Page Fields
articles collection
articles.content string Format (html)
articles.date_created date Auto
articles.date_published date
articles.date_updated date Auto (update)
articles.id objectid Primary
articles.meta_description string
articles.meta_keywords string
articles.meta_title string
articles.name string Name
Required
articles.parent link → /pages/{parent_id}
articles.parent_id objectid Required
Immutable
articles.published bool
articles.redirect string Format (url)
articles.slug string Format (slug)
Default
articles.tags array
content string Format (html)
date_created date Auto
date_published date
date_updated date Auto (update)
id objectid Primary
listing
Determines whether a page is a listing of articles
bool
meta_description string
meta_keywords string
meta_title string
name string Name
Required
published bool
redirect string Format (url)
slug string Format (slug)
Default
template string

Payments

Track invoice payments by credit card and other sources.

// Create a payment
$result = $client->post('/payments', array(
    'account_id' => '<payment account_id>',
    'amount' => '<payment amount>',
    'method' => '<payment method>',
    'card' => '<payment card>',
    ...
));

// Retrieve a payment
$result = $client->get('/payments/{id}', array(
    'id' => '<payment id>',
    ...
));

// Update a payment
$result = $client->put('/payments/{id}', array(
    'id' => '<payment id>',
    ...
));

// Delete a payment
$result = $client->delete('/payments/{id}', array(
    'id' => '<payment id>'
));
// Create a payment
client.post('/payments', { 
    account_id: '<payment account_id>',
    amount: '<payment amount>',
    method: '<payment method>',
    card: '<payment card>',
    ...
}, function(result) {
    ...
});

// Retrieve a payment
client.get('/payments/{id}', { id: '<payment id>', ... }, function(result) {
    ...
});

// Update a payment
client.put('/payments/{id}', { id: '<payment id>', ... }, function(result) {
    ...
});

// Delete a payment
client.delete('/payments/{id}', { id: '<payment id>' }, function(result) {
    ...
});
# Create a payment
curl -X POST https://api.schema.io/payments \ 
    -d 'account_id=<payment account_id>' \ 
    -d 'amount=<payment amount>' \ 
    -d 'method=<payment method>' \ 
    -d 'card=<payment card>' \ 

# Retrieve a payment
curl -G https://api.schema.io/payments/{id} \
    -d 'id=<payment id>' \

# Update a payment
curl -X PUT https://api.schema.io/payments/{id} \
    -d 'id=<payment id>' \

# Delete a payment
curl -X DELETE https://api.schema.io/payments/{id} \
    -d 'id=<payment id>' \
Payment Fields
account link → /accounts/{account_id}
account_card link → /accounts:cards/{account_card_id}
account_card_id objectid
account_id objectid Required
Immutable
Default
amount currency Required
Immutable
amount_refundable currency Read-only
Formula if(and(success, not(void)), amount - amount_refunded, 0)
amount_refunded currency Read-only
captured
Indicates the payment has been fully captured if applicable
bool
card
Payment card details if applicable
object
card.address_check string
card.brand string
card.cvc_check string
card.exp_month int
card.exp_year int
card.last4 string
card.test bool
card.token string Required
card.zip_check string
currency string
date_created date Auto
date_updated date Auto (update)
error
Error message returned by a gateway if applicable
object
error.code string
error.message string
gateway string Immutable
id objectid Primary
invoice link → /invoices/{invoice_id}
invoice_id objectid Immutable
method string Required
Immutable
number string Name
Auto
Immutable
order link → /orders/{order_id}
order_id objectid Immutable
Default
ref
External reference number
string
refunds collection
refunds.amount currency Required
Immutable
refunds.credit link → /credits/{credit_id}
refunds.credit_id objectid Immutable
refunds.currency string
refunds.date_created date Auto
refunds.date_updated date Auto (update)
refunds.error
Error message returned by a gateway where applicable
object
refunds.error.code string
refunds.error.message string
refunds.id objectid Primary
refunds.method string Required
refunds.number string Name
Auto
Immutable
refunds.order link → /orders/{order_id}
refunds.order_id objectid Immutable
Default
refunds.parent link → /payments/{parent_id}
refunds.parent_id objectid Required
Immutable
refunds.ref
External system identifier
string
refunds.status string Auto
Read-only
Enumerated (pending, void, error, success)
Default
refunds.subscription link → /subscriptions/{subscription_id}
refunds.subscription_id objectid Immutable
Default
refunds.success
Indicates whether the refund was successfully processed
bool Immutable
refunds.transaction_id
Refund transaction ID returned by a payment gateway if applicable
string
refunds.void bool Immutable
status string Auto
Read-only
Enumerated (pending, void, error, success)
Default
subscription link → /subscriptions/{subscription_id}
subscription_id objectid Immutable
Default
success
Indicates the payment transaction was successful
bool Immutable
transaction_id
Charge transaction ID returned by a payment gateway if applicable
string
void bool Immutable

Products

Products may be offered for sale to customers.

// Create a product
$result = $client->post('/products', array(
    'name' => '<product name>',
    'price' => 19.95,
    'sku' => 'T1000',
    'delivery' => 'shipment',
    'shipment_weight' => 1.5,
    'active' => true,
    ...
));

// Retrieve a product
$result = $client->get('/products/{id}', array(
    'id' => '<product id>',
    ...
));

// Update a product
$result = $client->put('/products/{id}', array(
    'id' => '<product id>',
    ...
));

// Delete a product
$result = $client->delete('/products/{id}', array(
    'id' => '<product id>'
));
// Create a product
client.post('/products', { 
    name: '<product name>',
    price: '<product price>',
    sku: '<product sku>',
    delivery: '<product delivery>',
    shipment_weight: '<product shipment_weight>',
    active: '<product active>',
    ...
}, function(result) {
    ...
});

// Retrieve a product
client.get('/products/{id}', { id: '<product id>', ... }, function(result) {
    ...
});

// Update a product
client.put('/products/{id}', { id: '<product id>', ... }, function(result) {
    ...
});

// Delete a product
client.delete('/products/{id}', { id: '<product id>' }, function(result) {
    ...
});
# Create a product
curl -X POST https://api.schema.io/products \ 
    -d 'name=<product name>' \ 
    -d 'price=<product price>' \ 
    -d 'sku=<product sku>' \ 
    -d 'delivery=<product delivery>' \ 
    -d 'shipment_weight=<product shipment_weight>' \ 
    -d 'active=<product active>' \ 

# Retrieve a product
curl -G https://api.schema.io/products/{id} \
    -d 'id=<product id>' \

# Update a product
curl -X PUT https://api.schema.io/products/{id} \
    -d 'id=<product id>' \

# Delete a product
curl -X DELETE https://api.schema.io/products/{id} \
    -d 'id=<product id>' \
Product Fields
active bool
attribute_set objectid
attributes object
bundle bool
bundle_items array
bundle_items.id objectid Primary
Auto
bundle_items.product link → /products/{product_id}
bundle_items.product_id objectid Required
bundle_items.quantity int Default
bundle_items.variant link → /products:variants/{variant_id}
bundle_items.variant_id objectid
categories link → /categories:products?product_id=id
category link → /categories/{category_id}
category_id objectid
category_index object
category_index.id array Primary
category_index.sort object
category_index.sort.* int
code
Product barcode, UPC, EAN, or ISBN
string
compare_price currency
cost currency
cross_sells array
cross_sells.discount_amount currency
cross_sells.discount_percent float
cross_sells.discount_type string Enumerated (fixed, percent)
cross_sells.id objectid Primary
Auto
cross_sells.product link → /products/{product_id}
cross_sells.product_id objectid Required
currency string
customizable
Indicates the product has custom options enabled
bool
date_created date Auto
date_stock_expected
Date stock is expected to become available
date
date_updated date Auto (update)
delivery string Enumerated (, shipment, subscription, download, booking, giftcard)
description string
discontinued bool
download_limit int
download_source string
id objectid Primary
images array
images.caption string
images.file file
images.file.content_type string
images.file.data filedata
images.file.date_uploaded date
images.file.filename string
images.file.height int
images.file.id objectid Primary
images.file.length int
images.file.md5 string
images.file.metadata object
images.file.url string
images.file.width int
images.id objectid Primary
Auto
meta_description string
meta_keywords string
meta_title string
name string Name
Required
options array
options.control
UI control type used to enter the option value
string Enumerated (text, select)
Default
options.id objectid Primary
Auto
options.input_hint string
options.input_multi bool
options.input_type string Enumerated (text, textarea, dropdown, checkbox, radio, image)
options.name
Name used to identify the option in user interfaces
string Name
Required
options.parent_id objectid
options.parent_value_ids array
options.price
Price added if the option is selected
currency
options.required
Indicates the option requires a value
bool Formula if(variant, true, required)
options.values
List of values for this option
array
options.values.id objectid Primary
Auto
options.values.name string Name
Required
options.values.price
Price added if the option value is selected
currency
options.values.shipment_weight
Shipment weight added if the option value is selected
float
options.variant
Indicates the option is an aspect of variants
bool
price currency
prices array
prices.account_group
Account group for which the rule is applied
string
prices.price
Price applied when conditions are met
currency Required
prices.quantity_max
Maximum quantity to apply price
int
prices.quantity_min
Minimum quantity to apply price
int
quantity_inc
Product must be ordered in multiples of this value
int
quantity_min
Minimum quantity of the product that can be ordered
int
related_category_id objectid
related_product_ids array
review_rating
Average rating value of all product reviews
float
reviews collection
reviews.account link → /accounts/{account_id}
reviews.account_id objectid
reviews.approved bool
reviews.comments string Required
reviews.date_created date Auto
reviews.date_updated date Auto (update)
reviews.id objectid Primary
reviews.name string Name
Required
Default
reviews.parent link → /products/{parent_id}
reviews.parent_id objectid Required
Immutable
reviews.rating int Required
Enumerated (1, 2, 3, 4, 5)
reviews.title string Required
sale bool
sale_price currency
shipment_location string
shipment_package_quantity float
shipment_prices array
shipment_prices.account_group string
shipment_prices.country string
shipment_prices.fee_amount currency
shipment_prices.fee_percent float
shipment_prices.fee_type string Enumerated (, fixed, percent)
shipment_prices.package_quantity int
shipment_prices.price currency
shipment_prices.service string Required
shipment_prices.state string
shipment_prices.total_max currency
shipment_prices.total_min currency
shipment_prices.weight_max float
shipment_prices.weight_min float
shipment_prices.zip string
shipment_weight float
sku string
slug string Default
stock
History of stock level adjustments for this product
collection
stock.date_created date Auto
stock.date_updated date Auto (update)
stock.description string
stock.id objectid Primary
stock.last link → /products:stock/:last?parent_id=parent_id&variant_id=variant_id
stock.level int Read-only
Immutable
Formula prev.level + quantity
stock.number string Auto
Immutable
stock.order link → /orders/{order_id}
stock.order_id objectid
stock.parent link → /products/{parent_id}
stock.parent_id objectid Required
Immutable
stock.prev link → /products:stock/{prev_id}
stock.prev_id objectid Immutable
Formula last.id
stock.quantity int Required
Immutable
stock.reason string Enumerated (received, returned, canceled, sold, missing, damaged)
stock.variant link → /products:variants/{variant_id}?parent_id=parent_id
stock.variant_id objectid Immutable
stock_backorder
Allow purchase while out of stock
bool
stock_level
Current stock level after all adjustments have been combined
int Read-only
stock_preorder
Enable product to be purchased with delayed charge
bool
stock_status
Status of product stock for the purpose of ordering
string Auto
Read-only
Enumerated (available, preorder, backorder, out_of_stock, discontinued)
stock_status_message
Custom description of product stock status
string
stock_tracking
Indicates the product has stock tracking enabled
bool
subscription_interval string Enumerated (monthly, daily, weekly, yearly)
subscription_interval_count int
subscription_trial_days int
summary string
tags array
tax_class string
type string
up_sells array
up_sells.id objectid Primary
Auto
up_sells.product link → /products/{product_id}
up_sells.product_id objectid Required
variable
Indicates the product has variants enabled
bool
variants
Variations represented as unique product options
collection
variants.active bool
variants.archived bool
variants.attributes object
variants.code
Product barcode, UPC, EAN, or ISBN
string
variants.compare_price currency
variants.currency string
variants.date_created date Auto
variants.date_updated date Auto (update)
variants.id objectid Primary
variants.image
Image used to represent this variant
link → /products/{parent_id}/images/{image_id}
variants.image_id objectid
variants.images array
variants.images.caption string
variants.images.file file
variants.images.file.content_type string
variants.images.file.data filedata
variants.images.file.date_uploaded date
variants.images.file.filename string
variants.images.file.height int
variants.images.file.id objectid Primary
variants.images.file.length int
variants.images.file.md5 string
variants.images.file.metadata object
variants.images.file.url string
variants.images.file.width int
variants.images.id objectid Primary
Auto
variants.name string Name
Required
variants.option_value_ids array
variants.parent link → /products/{parent_id}
variants.parent_id objectid Required
Immutable
variants.price currency
variants.sale bool
variants.sale_price currency
variants.shipment_weight float
variants.sku string
variants.stock_level int Read-only
variants.subscription_interval string Enumerated (monthly, daily, weekly, yearly)
variants.subscription_interval_count int
variants.subscription_trial_days int
virtual bool

Promotions

// Create a promotion
$result = $client->post('/promotions', array(
    'name' => '<promotion name>',
    ...
));

// Retrieve a promotion
$result = $client->get('/promotions/{id}', array(
    'id' => '<promotion id>',
    ...
));

// Update a promotion
$result = $client->put('/promotions/{id}', array(
    'id' => '<promotion id>',
    ...
));

// Delete a promotion
$result = $client->delete('/promotions/{id}', array(
    'id' => '<promotion id>'
));
// Create a promotion
client.post('/promotions', { 
    name: '<promotion name>',
    ...
}, function(result) {
    ...
});

// Retrieve a promotion
client.get('/promotions/{id}', { id: '<promotion id>', ... }, function(result) {
    ...
});

// Update a promotion
client.put('/promotions/{id}', { id: '<promotion id>', ... }, function(result) {
    ...
});

// Delete a promotion
client.delete('/promotions/{id}', { id: '<promotion id>' }, function(result) {
    ...
});
# Create a promotion
curl -X POST https://api.schema.io/promotions \ 
    -d 'name=<promotion name>' \ 

# Retrieve a promotion
curl -G https://api.schema.io/promotions/{id} \
    -d 'id=<promotion id>' \

# Update a promotion
curl -X PUT https://api.schema.io/promotions/{id} \
    -d 'id=<promotion id>' \

# Delete a promotion
curl -X DELETE https://api.schema.io/promotions/{id} \
    -d 'id=<promotion id>' \
Promotion Fields
active bool
currency string
date_created date Auto
date_end
Date the promotion automatically ends and no longer applicable
date
date_start
Date the promotion is first applicable
date
date_updated date Auto (update)
description string
discount_group
Group of discounts for which one exclusive set of rules can apply at a time
string
discounts
Discount rules considered when the promotion is applied
array
discounts.category link → /categories/{category_id}
discounts.category_id
Category identifier for which a rule will apply
objectid
discounts.price_min
Minimum product price required for a rule to apply
currency
discounts.product link → /products/{product_id}
discounts.product_id
Product identifier for which a rule will apply
objectid
discounts.quantity_max
Maximum product quantity for which a rule will apply
int
discounts.quantity_min
Minimum product quantity required for a rule to apply
int
discounts.shipment_service
Shipment service to apply discount if applicable
string
discounts.total_min
Minimum order total required for a rule to apply
currency
discounts.type string Enumerated (total, shipment, product, category)
Default
discounts.value
Fixed value of discount (deprecated)
currency
discounts.value_fixed
Fixed value of discount
currency
discounts.value_percent
Percentage value of discount
float
discounts.value_type string Required
Enumerated (fixed, percent)
Default
discounts.variant link → /products:variants/{variant_id}
discounts.variant_id
Variant identifier for which a rule will apply
objectid
exclusions
Exclusion rules considered when the promotion is applied
array
exclusions.category link → /categories/{category_id}
exclusions.category_id
Category identifier for which a rule will apply
objectid
exclusions.product link → /products/{product_id}
exclusions.product_id
Product identifier for which a rule will apply
objectid
exclusions.type string Required
Enumerated (product, category)
id objectid Primary
limit_account_groups
Account groups that may apply the promotion
array
limit_account_segments
Account segments that may apply the promotion
array
limit_account_uses
Maximum number of times the promotion may be applied by each account
int
limit_uses
Maximum number of times the promotion may be applied
int
name string Name
Required
orders link → /orders?promotion_ids=id
subscriptions link → /subscriptions?promotion_ids=id
use_count
Number of times a promotion has been applied
int
uses collection
uses.account_id objectid Immutable
uses.date_created date Auto
uses.date_updated date Auto (update)
uses.id objectid Primary
uses.order link → /orders/{order_id}
uses.order_id objectid Immutable
uses.parent link → /promotions/{parent_id}
uses.parent_id objectid Required
Immutable
uses.subscription link → /subscriptions/{subscription_id}
uses.subscription_id objectid Immutable

Settings

// Create a setting
$result = $client->post('/settings', array(
    'id' => '<setting id>',
    ...
));

// Retrieve a setting
$result = $client->get('/settings/{id}', array(
    'id' => '<setting id>',
    ...
));

// Update a setting
$result = $client->put('/settings/{id}', array(
    'id' => '<setting id>',
    ...
));

// Delete a setting
$result = $client->delete('/settings/{id}', array(
    'id' => '<setting id>'
));
// Create a setting
client.post('/settings', { 
    id: '<setting id>',
    ...
}, function(result) {
    ...
});

// Retrieve a setting
client.get('/settings/{id}', { id: '<setting id>', ... }, function(result) {
    ...
});

// Update a setting
client.put('/settings/{id}', { id: '<setting id>', ... }, function(result) {
    ...
});

// Delete a setting
client.delete('/settings/{id}', { id: '<setting id>' }, function(result) {
    ...
});
# Create a setting
curl -X POST https://api.schema.io/settings \ 
    -d 'id=<setting id>' \ 

# Retrieve a setting
curl -G https://api.schema.io/settings/{id} \
    -d 'id=<setting id>' \

# Update a setting
curl -X PUT https://api.schema.io/settings/{id} \
    -d 'id=<setting id>' \

# Delete a setting
curl -X DELETE https://api.schema.io/settings/{id} \
    -d 'id=<setting id>' \
Setting Fields
date_created date Auto
date_updated date Auto (update)
id string Primary
Required

Shipments

Track physical product shipments to customers.

// Create a shipment
$result = $client->post('/shipments', array(
    'items' => '<shipment items>',
    'order_id' => '<shipment order_id>',
    ...
));

// Retrieve a shipment
$result = $client->get('/shipments/{id}', array(
    'id' => '<shipment id>',
    ...
));

// Update a shipment
$result = $client->put('/shipments/{id}', array(
    'id' => '<shipment id>',
    ...
));

// Delete a shipment
$result = $client->delete('/shipments/{id}', array(
    'id' => '<shipment id>'
));
// Create a shipment
client.post('/shipments', { 
    items: '<shipment items>',
    order_id: '<shipment order_id>',
    ...
}, function(result) {
    ...
});

// Retrieve a shipment
client.get('/shipments/{id}', { id: '<shipment id>', ... }, function(result) {
    ...
});

// Update a shipment
client.put('/shipments/{id}', { id: '<shipment id>', ... }, function(result) {
    ...
});

// Delete a shipment
client.delete('/shipments/{id}', { id: '<shipment id>' }, function(result) {
    ...
});
# Create a shipment
curl -X POST https://api.schema.io/shipments \ 
    -d 'items=<shipment items>' \ 
    -d 'order_id=<shipment order_id>' \ 

# Retrieve a shipment
curl -G https://api.schema.io/shipments/{id} \
    -d 'id=<shipment id>' \

# Update a shipment
curl -X PUT https://api.schema.io/shipments/{id} \
    -d 'id=<shipment id>' \

# Delete a shipment
curl -X DELETE https://api.schema.io/shipments/{id} \
    -d 'id=<shipment id>' \
Shipment Fields
canceled bool
carrier string
carrier_name string
date_created date Auto
date_delivery_estimated date
date_updated date Auto (update)
destination object Default
destination.address1 string Required
destination.address2 string
destination.city string
destination.country string Required
destination.name string Required
destination.phone string
destination.state string
destination.zip string
id objectid Primary
Name
items array Required
items.bundle_item_id objectid
items.id objectid Primary
Name
Auto
items.options array
items.options.id string Primary
Name
items.options.name string
items.options.value string
items.order_item_id objectid
items.product link → /products/{product_id}
items.product_id objectid Required
items.quantity int
items.variant link → /products:variants/{variant_id}
items.variant_id objectid
label object
label.date_created date Auto
label.date_purchased date Immutable
label.image file
label.image.content_type string
label.image.data filedata
label.image.date_uploaded date
label.image.filename string
label.image.height int
label.image.id objectid Primary
Name
label.image.length int
label.image.md5 string
label.image.metadata object
label.image.url string
label.image.width int
label.purhcase bool Immutable
notifications link → /notifications?record_id=id
number string Auto
Immutable
order link → /orders/{order_id}
order_id objectid Required
Immutable
origin object
origin.location string Default
packages array
packages.height float
packages.length float
packages.type string
packages.weight float
packages.width float
service string
service_name string
tracking_code string

Subscriptions

// Create a subscription
$result = $client->post('/subscriptions', array(
    'account_id' => '<subscription account_id>',
    'product_id' => '<subscription product_id>',
    ...
));

// Retrieve a subscription
$result = $client->get('/subscriptions/{id}', array(
    'id' => '<subscription id>',
    ...
));

// Update a subscription
$result = $client->put('/subscriptions/{id}', array(
    'id' => '<subscription id>',
    ...
));

// Delete a subscription
$result = $client->delete('/subscriptions/{id}', array(
    'id' => '<subscription id>'
));
// Create a subscription
client.post('/subscriptions', { 
    account_id: '<subscription account_id>',
    product_id: '<subscription product_id>',
    ...
}, function(result) {
    ...
});

// Retrieve a subscription
client.get('/subscriptions/{id}', { id: '<subscription id>', ... }, function(result) {
    ...
});

// Update a subscription
client.put('/subscriptions/{id}', { id: '<subscription id>', ... }, function(result) {
    ...
});

// Delete a subscription
client.delete('/subscriptions/{id}', { id: '<subscription id>' }, function(result) {
    ...
});
# Create a subscription
curl -X POST https://api.schema.io/subscriptions \ 
    -d 'account_id=<subscription account_id>' \ 
    -d 'product_id=<subscription product_id>' \ 

# Retrieve a subscription
curl -G https://api.schema.io/subscriptions/{id} \
    -d 'id=<subscription id>' \

# Update a subscription
curl -X PUT https://api.schema.io/subscriptions/{id} \
    -d 'id=<subscription id>' \

# Delete a subscription
curl -X DELETE https://api.schema.io/subscriptions/{id} \
    -d 'id=<subscription id>' \
Subscription Fields
account link → /accounts/{account_id}
account_id objectid Required
Immutable
active bool Read-only
cancel_at_end bool
cancel_reason string
canceled bool Immutable
coupon link → /coupons/{coupon_id}
coupon_code string
coupon_id objectid
credit_total currency Read-only
credits link → /credits?subscription_id=id
currency string Immutable
date_canceled date Read-only
date_created date Auto
date_payment_retry date
date_period_end date Read-only
Formula if(date_trial_end > now(), date_trial_end, date_period_end)
date_period_start date Read-only
date_prorated date
date_trial_end date
date_trial_start date Read-only
date_updated date Auto (update)
discount_total currency Formula sum(discounts.amount)
discounts array
discounts.amount currency
discounts.id string Primary
discounts.rule object
discounts.type string Enumerated (sale, coupon)
grand_total currency Formula sub_total + tax_included_total - (discount_total)
id objectid Primary
interval string Enumerated (monthly, daily, weekly, yearly)
interval_count int
invoices link → /invoices?subscription_id=id
item_discount currency Formula sum(items.discount_total)
item_tax currency Formula sum(items.tax_total)
item_total currency Formula sum(items.price_total)
items array
items.date_created date Auto
Immutable
items.description string
items.discount_each currency Formula discount_total / quantity
items.discount_total currency Formula sum(discounts.amount)
items.discounts array
items.discounts.amount currency
items.discounts.id string Primary
items.id objectid Primary
Auto
Immutable
items.price currency
items.price_total currency Formula price * quantity
items.product link → /products/{product_id}
items.product_id objectid Immutable
items.proration bool
items.quantity int Default
items.recurring bool
items.recurring_discount_each currency Formula if(recurring, discount_total / quantity, 0)
items.recurring_discount_total currency Formula if(recurring, sum(discounts.amount), 0)
items.recurring_price currency Formula if(recurring, price, 0)
items.recurring_price_total currency Formula if(recurring, price_total, 0)
items.recurring_tax_each currency Formula if(recurring, tax_total / quantity, 0)
items.recurring_tax_total currency Formula if(recurring, sum(taxes.amount), 0)
items.tax_each currency Formula tax_total / quantity
items.tax_total currency Formula sum(taxes.amount)
items.taxes array
items.taxes.amount currency
items.taxes.id string Primary
items.variant link → /products:variants/{variant_id}
items.variant_id objectid Immutable
paid bool Read-only
Formula if(and(not(trial), payment_balance >= 0), true, false)
payment_balance currency Formula payment_total - refund_total - grand_total + (credit_total) + (item_total)
payment_total currency Read-only
payments link → /payments?subscription_id=id
pending_credits link → /credits?subscription_id=id?status=pending
pending_invoices link → /invoices?subscription_id=id?status=pending
price currency
price_total currency Formula price * quantity
product link → /products/{product_id}
product_discount_each currency Formula product_discount_total / quantity
product_discount_total currency Formula sum(product_discounts.amount)
product_discounts array
product_discounts.amount currency
product_discounts.id string Primary
product_id objectid Required
product_tax_each currency Formula product_tax_total / quantity
product_tax_total currency Formula sum(product_taxes.amount)
product_taxes array
product_taxes.amount currency
product_taxes.id string Primary
prorated bool
quantity int Default
recurring_discount_total currency Formula product_discount_total + recurring_item_discount
recurring_item_discount currency Formula sum(items.recurring_discount_total)
recurring_item_tax currency Formula sum(items.recurring_tax_total)
recurring_item_total currency Formula sum(items.recurring_price_total)
recurring_tax_included_total currency Formula if(tax_included, 0, recurring_tax_total)
recurring_tax_total currency Formula product_tax_total + recurring_item_tax
recurring_total currency Formula price_total + recurring_item_total + recurring_tax_included_total - recurring_discount_total
recycle bool
refund_total currency Read-only
refunds link → /payments:refunds?subscription_id=id
status string Auto
Read-only
Enumerated (pending, active, trial, pastdue, unpaid, canceled, paid)
sub_total currency Formula price_total + item_total
tax_included bool
tax_included_total currency Formula if(tax_included, 0, tax_total)
tax_total currency Formula sum(taxes.amount)
taxes array
taxes.amount currency
taxes.id string Primary
taxes.name string
taxes.priority int
taxes.rate float
trial bool Read-only
Formula date_trial_end > now()
trial_days int Immutable
unpaid bool Formula if(not(paid), unpaid, false)
variant link → /products:variants/{variant_id}?parent_id=product_id
variant_id objectid

Webhooks

// Create a webhook
$result = $client->post('/webhooks', array(
    'record_id' => '<webhook record_id>',
    'webhook' => '<webhook webhook>',
    ...
));

// Retrieve a webhook
$result = $client->get('/webhooks/{id}', array(
    'id' => '<webhook id>',
    ...
));

// Update a webhook
$result = $client->put('/webhooks/{id}', array(
    'id' => '<webhook id>',
    ...
));

// Delete a webhook
$result = $client->delete('/webhooks/{id}', array(
    'id' => '<webhook id>'
));
// Create a webhook
client.post('/webhooks', { 
    record_id: '<webhook record_id>',
    webhook: '<webhook webhook>',
    ...
}, function(result) {
    ...
});

// Retrieve a webhook
client.get('/webhooks/{id}', { id: '<webhook id>', ... }, function(result) {
    ...
});

// Update a webhook
client.put('/webhooks/{id}', { id: '<webhook id>', ... }, function(result) {
    ...
});

// Delete a webhook
client.delete('/webhooks/{id}', { id: '<webhook id>' }, function(result) {
    ...
});
# Create a webhook
curl -X POST https://api.schema.io/webhooks \ 
    -d 'record_id=<webhook record_id>' \ 
    -d 'webhook=<webhook webhook>' \ 

# Retrieve a webhook
curl -G https://api.schema.io/webhooks/{id} \
    -d 'id=<webhook id>' \

# Update a webhook
curl -X PUT https://api.schema.io/webhooks/{id} \
    -d 'id=<webhook id>' \

# Delete a webhook
curl -X DELETE https://api.schema.io/webhooks/{id} \
    -d 'id=<webhook id>' \
Webhook Fields
config link → /:webhooks/{webhook}
date_created date Auto
date_retry date
date_updated date Auto (update)
error
Error message returned by sending process if applicable
string
id objectid Primary
record link → /{config.model}/{record_id}
record_id
Record ID of the collection for which the webhook is defined
objectid Required
retry_count int
url
Notification contact address if applicable
string
webhook
Webhook name
string Required

Meta Models

Meta models provide access to system settings and information.

Clients

// Create a client
$result = $client->post('/:clients', array(
    'api' => '<client api>',
    'id' => '<client id>',
    'name' => '<client name>',
    ...
));

// Retrieve a client
$result = $client->get('/:clients/{id}', array(
    'id' => '<client id>',
    ...
));

// Update a client
$result = $client->put('/:clients/{id}', array(
    'id' => '<client id>',
    ...
));

// Delete a client
$result = $client->delete('/:clients/{id}', array(
    'id' => '<client id>'
));
// Create a client
client.post('/:clients', { 
    api: '<client api>',
    id: '<client id>',
    name: '<client name>',
    ...
}, function(result) {
    ...
});

// Retrieve a client
client.get('/:clients/{id}', { id: '<client id>', ... }, function(result) {
    ...
});

// Update a client
client.put('/:clients/{id}', { id: '<client id>', ... }, function(result) {
    ...
});

// Delete a client
client.delete('/:clients/{id}', { id: '<client id>' }, function(result) {
    ...
});
# Create a client
curl -X POST https://api.schema.io/:clients \ 
    -d 'api=<client api>' \ 
    -d 'id=<client id>' \ 
    -d 'name=<client name>' \ 

# Retrieve a client
curl -G https://api.schema.io/:clients/{id} \
    -d 'id=<client id>' \

# Update a client
curl -X PUT https://api.schema.io/:clients/{id} \
    -d 'id=<client id>' \

# Delete a client
curl -X DELETE https://api.schema.io/:clients/{id} \
    -d 'id=<client id>' \
Client Fields
api string Required
clients link → /clients?parent_id=id
currency string Default
date_created date Auto
date_updated date Auto (update)
env string Enumerated (development, staging, production)
Default
id string Required
Immutable
Format (slug)
Default
keys collection
locale string
master bool
name string Required
owner_id objectid
parent link → /clients/{parent_id}
parent_id objectid
sites collection
support_email string Format (email)
timezone string
usage object
usage.data_gb float
usage.data_mb float
usage.index_gb float
usage.index_mb float
usage.shipment_labels_billable int
usage.shipment_labels_total int
usage.total_docs int
usage.total_gb float
usage.total_mb float
users link → /users?client_id=id
v2 bool

Currencies

// Create a currency
$result = $client->post('/:currencies', array(
    'name' => '<currency name>',
    ...
));

// Retrieve a currency
$result = $client->get('/:currencies/{id}', array(
    'id' => '<currency id>',
    ...
));

// Update a currency
$result = $client->put('/:currencies/{id}', array(
    'id' => '<currency id>',
    ...
));

// Delete a currency
$result = $client->delete('/:currencies/{id}', array(
    'id' => '<currency id>'
));
// Create a currency
client.post('/:currencies', { 
    name: '<currency name>',
    ...
}, function(result) {
    ...
});

// Retrieve a currency
client.get('/:currencies/{id}', { id: '<currency id>', ... }, function(result) {
    ...
});

// Update a currency
client.put('/:currencies/{id}', { id: '<currency id>', ... }, function(result) {
    ...
});

// Delete a currency
client.delete('/:currencies/{id}', { id: '<currency id>' }, function(result) {
    ...
});
# Create a currency
curl -X POST https://api.schema.io/:currencies \ 
    -d 'name=<currency name>' \ 

# Retrieve a currency
curl -G https://api.schema.io/:currencies/{id} \
    -d 'id=<currency id>' \

# Update a currency
curl -X PUT https://api.schema.io/:currencies/{id} \
    -d 'id=<currency id>' \

# Delete a currency
curl -X DELETE https://api.schema.io/:currencies/{id} \
    -d 'id=<currency id>' \
Currency Fields

Files

// Create a file
$result = $client->post('/:files', array(
    'name' => '<file name>',
    ...
));

// Retrieve a file
$result = $client->get('/:files/{id}', array(
    'id' => '<file id>',
    ...
));

// Update a file
$result = $client->put('/:files/{id}', array(
    'id' => '<file id>',
    ...
));

// Delete a file
$result = $client->delete('/:files/{id}', array(
    'id' => '<file id>'
));
// Create a file
client.post('/:files', { 
    name: '<file name>',
    ...
}, function(result) {
    ...
});

// Retrieve a file
client.get('/:files/{id}', { id: '<file id>', ... }, function(result) {
    ...
});

// Update a file
client.put('/:files/{id}', { id: '<file id>', ... }, function(result) {
    ...
});

// Delete a file
client.delete('/:files/{id}', { id: '<file id>' }, function(result) {
    ...
});
# Create a file
curl -X POST https://api.schema.io/:files \ 
    -d 'name=<file name>' \ 

# Retrieve a file
curl -G https://api.schema.io/:files/{id} \
    -d 'id=<file id>' \

# Update a file
curl -X PUT https://api.schema.io/:files/{id} \
    -d 'id=<file id>' \

# Delete a file
curl -X DELETE https://api.schema.io/:files/{id} \
    -d 'id=<file id>' \
File Fields
aliases array
chunkSize int Read-only
contentType string Read-only
data filedata
filename string
id objectid
length int Read-only
md5 string Read-only
metadata object
uploadDate date Read-only

Layouts

// Create a layout
$result = $client->post('/:layouts', array(
    'api' => '<layout api>',
    'model' => '<layout model>',
    'name' => '<layout name>',
    'type' => '<layout type>',
    ...
));

// Retrieve a layout
$result = $client->get('/:layouts/{id}', array(
    'id' => '<layout id>',
    ...
));

// Update a layout
$result = $client->put('/:layouts/{id}', array(
    'id' => '<layout id>',
    ...
));

// Delete a layout
$result = $client->delete('/:layouts/{id}', array(
    'id' => '<layout id>'
));
// Create a layout
client.post('/:layouts', { 
    api: '<layout api>',
    model: '<layout model>',
    name: '<layout name>',
    type: '<layout type>',
    ...
}, function(result) {
    ...
});

// Retrieve a layout
client.get('/:layouts/{id}', { id: '<layout id>', ... }, function(result) {
    ...
});

// Update a layout
client.put('/:layouts/{id}', { id: '<layout id>', ... }, function(result) {
    ...
});

// Delete a layout
client.delete('/:layouts/{id}', { id: '<layout id>' }, function(result) {
    ...
});
# Create a layout
curl -X POST https://api.schema.io/:layouts \ 
    -d 'api=<layout api>' \ 
    -d 'model=<layout model>' \ 
    -d 'name=<layout name>' \ 
    -d 'type=<layout type>' \ 

# Retrieve a layout
curl -G https://api.schema.io/:layouts/{id} \
    -d 'id=<layout id>' \

# Update a layout
curl -X PUT https://api.schema.io/:layouts/{id} \
    -d 'id=<layout id>' \

# Delete a layout
curl -X DELETE https://api.schema.io/:layouts/{id} \
    -d 'id=<layout id>' \
Layout Fields
actions object
api string Required
Format (slug)
client_id string Format (slug)
date_created date Auto
date_updated date Auto (update)
extends
Parent layout
string
extends_version
Extended parent version
string Format (semver)
id string Formula slugid(client_id, api, if(scope, model+':'+scope, model), name)
label string
model string Required
Format (slug)
name string Required
Format (slug)
query object
scope string Format (slug)
sections object
subtitle
Layout subtitle field
object
title
Layout title field
object
type
Type of layout
string Required
Enumerated (collection, record)
version string Format (semver)
Default
versions collection
workflow object

Models

// Create a model
$result = $client->post('/:models', array(
    'api' => '<model api>',
    'name' => '<model name>',
    ...
));

// Retrieve a model
$result = $client->get('/:models/{id}', array(
    'id' => '<model id>',
    ...
));

// Update a model
$result = $client->put('/:models/{id}', array(
    'id' => '<model id>',
    ...
));

// Delete a model
$result = $client->delete('/:models/{id}', array(
    'id' => '<model id>'
));
// Create a model
client.post('/:models', { 
    api: '<model api>',
    name: '<model name>',
    ...
}, function(result) {
    ...
});

// Retrieve a model
client.get('/:models/{id}', { id: '<model id>', ... }, function(result) {
    ...
});

// Update a model
client.put('/:models/{id}', { id: '<model id>', ... }, function(result) {
    ...
});

// Delete a model
client.delete('/:models/{id}', { id: '<model id>' }, function(result) {
    ...
});
# Create a model
curl -X POST https://api.schema.io/:models \ 
    -d 'api=<model api>' \ 
    -d 'name=<model name>' \ 

# Retrieve a model
curl -G https://api.schema.io/:models/{id} \
    -d 'id=<model id>' \

# Update a model
curl -X PUT https://api.schema.io/:models/{id} \
    -d 'id=<model id>' \

# Delete a model
curl -X DELETE https://api.schema.io/:models/{id} \
    -d 'id=<model id>' \
Model Fields
api string Required
Format (slug)
client_id string Format (slug)
date_created date Auto
date_updated date Auto (update)
events
Model event configuration
object
events.enabled bool
events.root
Root name of event types used in webhooks
string
events.types
Event types triggered by the model
array
events.types.conditions object
events.types.id string Required
extends
Parent model
string
extends_version
Extended parent version
string Format (semver)
features
Model feature configuration
object
fields object
fields.* object
fields.*.auto mixed
fields.*.default {type}
fields.*.description string
fields.*.enum array
fields.*.fields object
fields.*.format string
fields.*.formula string
fields.*.increment object
fields.*.indexes array
fields.*.indexes.fields object
fields.*.indexes.fields.* int
fields.*.indexes.name string
fields.*.indexes.options object
fields.*.indexes.options.expire_seconds int
fields.*.key string
fields.*.label string
fields.*.length int
fields.*.max float
fields.*.maxlength int
fields.*.min float
fields.*.minlength int
fields.*.model string
fields.*.multiline bool
fields.*.plural string
fields.*.readonly bool
fields.*.required bool
fields.*.rules array
fields.*.rules.error string
fields.*.rules.expression string
fields.*.sort string
fields.*.type string Enumerated (array, bool, collection, currency, date, float, int, link, string, object, objectid)
fields.*.unique mixed
fields.*.value_type string Enumerated (array, bool, currency, date, float, int, link, string, object, objectid)
id string Formula slugid(client_id, api, name)
indexes array
indexes.fields object
indexes.fields.* int
indexes.name string
indexes.options object
indexes.options.expire_seconds int
label
Singular name of a model instance
string
name string Required
Format (slug)
name_field
Field used to identify a record in user interfaces
string
plural
Plural name of a model collection
string
primary_field
Primary lookup field
string Default
query
Default query parameters
object
query.limit int
query.page int
query.sort string
query.window int
secondary_field
Secondary lookup field
string
triggers
Model trigger configuration
array
triggers.actions array Required
triggers.actions.data any
triggers.actions.key string
triggers.actions.method string
triggers.actions.model string
triggers.actions.params object
triggers.actions.type string
triggers.conditions object
triggers.events array Required
triggers.id objectid Auto
triggers.include object
triggers.label string
version string Format (semver)
Default
versions collection

Notifications

// Create a notification
$result = $client->post('/:notifications', array(
    'api' => '<notification api>',
    'model' => '<notification model>',
    'name' => '<notification name>',
    ...
));

// Retrieve a notification
$result = $client->get('/:notifications/{id}', array(
    'id' => '<notification id>',
    ...
));

// Update a notification
$result = $client->put('/:notifications/{id}', array(
    'id' => '<notification id>',
    ...
));

// Delete a notification
$result = $client->delete('/:notifications/{id}', array(
    'id' => '<notification id>'
));
// Create a notification
client.post('/:notifications', { 
    api: '<notification api>',
    model: '<notification model>',
    name: '<notification name>',
    ...
}, function(result) {
    ...
});

// Retrieve a notification
client.get('/:notifications/{id}', { id: '<notification id>', ... }, function(result) {
    ...
});

// Update a notification
client.put('/:notifications/{id}', { id: '<notification id>', ... }, function(result) {
    ...
});

// Delete a notification
client.delete('/:notifications/{id}', { id: '<notification id>' }, function(result) {
    ...
});
# Create a notification
curl -X POST https://api.schema.io/:notifications \ 
    -d 'api=<notification api>' \ 
    -d 'model=<notification model>' \ 
    -d 'name=<notification name>' \ 

# Retrieve a notification
curl -G https://api.schema.io/:notifications/{id} \
    -d 'id=<notification id>' \

# Update a notification
curl -X PUT https://api.schema.io/:notifications/{id} \
    -d 'id=<notification id>' \

# Delete a notification
curl -X DELETE https://api.schema.io/:notifications/{id} \
    -d 'id=<notification id>' \
Notification Fields
admin
Indicates a notification is intended for Admin Users
bool
api string Required
Format (slug)
client_id string Format (slug)
conditions
Record conditions required to trigger notification
object
contact
Model field containing the relevant contact address
string
content object
content.html file
content.html.content_type string
content.html.data filedata
content.html.date_uploaded date
content.html.filename string
content.html.height int
content.html.id objectid
content.html.length int
content.html.md5 string
content.html.metadata object
content.html.url string
content.html.width int
content.text file
content.text.content_type string
content.text.data filedata
content.text.date_uploaded date
content.text.filename string
content.text.height int
content.text.id objectid
content.text.length int
content.text.md5 string
content.text.metadata object
content.text.url string
content.text.width int
date_created date Auto
date_updated date Auto (update)
delay
Number of minutes to delay the notification if applicable
int
enabled bool Default
extends
Parent notification
string
extends_version
Extended parent version
string Format (semver)
id string Formula slugid(client_id, api, model, name)
label string
method string Enumerated (email)
Default
model string Required
Format (slug)
name string Required
Format (slug)
new
Indicates a notification should be triggered by newly created records only
bool
repeat
Indicates a notification should be triggered repeatedly on a single record
bool
replyto
Reply to address used instead of default if applicable
string
subject
Subject of notification if applicable
string
version string Format (semver)
Default

Sessions

// Create a session
$result = $client->post('/:sessions', array(
    'id' => '<session id>',
    ...
));

// Retrieve a session
$result = $client->get('/:sessions/{id}', array(
    'id' => '<session id>',
    ...
));

// Update a session
$result = $client->put('/:sessions/{id}', array(
    'id' => '<session id>',
    ...
));

// Delete a session
$result = $client->delete('/:sessions/{id}', array(
    'id' => '<session id>'
));
// Create a session
client.post('/:sessions', { 
    id: '<session id>',
    ...
}, function(result) {
    ...
});

// Retrieve a session
client.get('/:sessions/{id}', { id: '<session id>', ... }, function(result) {
    ...
});

// Update a session
client.put('/:sessions/{id}', { id: '<session id>', ... }, function(result) {
    ...
});

// Delete a session
client.delete('/:sessions/{id}', { id: '<session id>' }, function(result) {
    ...
});
# Create a session
curl -X POST https://api.schema.io/:sessions \ 
    -d 'id=<session id>' \ 

# Retrieve a session
curl -G https://api.schema.io/:sessions/{id} \
    -d 'id=<session id>' \

# Update a session
curl -X PUT https://api.schema.io/:sessions/{id} \
    -d 'id=<session id>' \

# Delete a session
curl -X DELETE https://api.schema.io/:sessions/{id} \
    -d 'id=<session id>' \
Session Fields
date_created date Auto
date_updated date Auto (update)
id string Required
Default

Settings

// Create a setting
$result = $client->post('/:settings', array(
    'api' => '<setting api>',
    'name' => '<setting name>',
    ...
));

// Retrieve a setting
$result = $client->get('/:settings/{id}', array(
    'id' => '<setting id>',
    ...
));

// Update a setting
$result = $client->put('/:settings/{id}', array(
    'id' => '<setting id>',
    ...
));

// Delete a setting
$result = $client->delete('/:settings/{id}', array(
    'id' => '<setting id>'
));
// Create a setting
client.post('/:settings', { 
    api: '<setting api>',
    name: '<setting name>',
    ...
}, function(result) {
    ...
});

// Retrieve a setting
client.get('/:settings/{id}', { id: '<setting id>', ... }, function(result) {
    ...
});

// Update a setting
client.put('/:settings/{id}', { id: '<setting id>', ... }, function(result) {
    ...
});

// Delete a setting
client.delete('/:settings/{id}', { id: '<setting id>' }, function(result) {
    ...
});
# Create a setting
curl -X POST https://api.schema.io/:settings \ 
    -d 'api=<setting api>' \ 
    -d 'name=<setting name>' \ 

# Retrieve a setting
curl -G https://api.schema.io/:settings/{id} \
    -d 'id=<setting id>' \

# Update a setting
curl -X PUT https://api.schema.io/:settings/{id} \
    -d 'id=<setting id>' \

# Delete a setting
curl -X DELETE https://api.schema.io/:settings/{id} \
    -d 'id=<setting id>' \
Setting Fields
api string Required
Format (slug)
client_id string Format (slug)
date_created date Auto
date_updated date Auto (update)
defaults
Setting default values
object
extends
Parent setting
string
extends_version
Extended parent version
string Format (semver)
fields
Setting fields
object
id string Formula slugid(client_id, api, name)
label string
name string Required
Format (slug)
version string Format (semver)
Default

Users

// Create a user
$result = $client->post('/:users', array(
    'client_id' => '<user client_id>',
    'email' => '<user email>',
    'name' => '<user name>',
    'username' => '<user username>',
    ...
));

// Retrieve a user
$result = $client->get('/:users/{id}', array(
    'id' => '<user id>',
    ...
));

// Update a user
$result = $client->put('/:users/{id}', array(
    'id' => '<user id>',
    ...
));

// Delete a user
$result = $client->delete('/:users/{id}', array(
    'id' => '<user id>'
));
// Create a user
client.post('/:users', { 
    client_id: '<user client_id>',
    email: '<user email>',
    name: '<user name>',
    username: '<user username>',
    ...
}, function(result) {
    ...
});

// Retrieve a user
client.get('/:users/{id}', { id: '<user id>', ... }, function(result) {
    ...
});

// Update a user
client.put('/:users/{id}', { id: '<user id>', ... }, function(result) {
    ...
});

// Delete a user
client.delete('/:users/{id}', { id: '<user id>' }, function(result) {
    ...
});
# Create a user
curl -X POST https://api.schema.io/:users \ 
    -d 'client_id=<user client_id>' \ 
    -d 'email=<user email>' \ 
    -d 'name=<user name>' \ 
    -d 'username=<user username>' \ 

# Retrieve a user
curl -G https://api.schema.io/:users/{id} \
    -d 'id=<user id>' \

# Update a user
curl -X PUT https://api.schema.io/:users/{id} \
    -d 'id=<user id>' \

# Delete a user
curl -X DELETE https://api.schema.io/:users/{id} \
    -d 'id=<user id>' \
User Fields
client link → /clients/{client_id}
client_id string Required
date_created date Auto
date_last_login date
date_updated date Auto (update)
email
Contact email address
string Required
Format (email)
id objectid
invite_url
Single use URL for signup by invite
string Format (url)
invited bool
name string Required
notifications array
notifications.enabled bool Default
notifications.template string
notify bool
password string Format (password)
password_reset_key
Single use key for password reset
string
password_reset_url
Single use URL for password reset
string Format (url)
phone string
photo file
photo.content_type string
photo.data filedata
photo.date_uploaded date
photo.filename string
photo.height int
photo.id objectid
photo.length int
photo.md5 string
photo.metadata object
photo.url string
photo.width int
role string Default
username
User name formatted as email address for login
string Required
Format (email)
Default

Webhooks

// Create a webhook
$result = $client->post('/:webhooks', array(
    'api' => '<webhook api>',
    'events' => '<webhook events>',
    'url' => '<webhook url>',
    ...
));

// Retrieve a webhook
$result = $client->get('/:webhooks/{id}', array(
    'id' => '<webhook id>',
    ...
));

// Update a webhook
$result = $client->put('/:webhooks/{id}', array(
    'id' => '<webhook id>',
    ...
));

// Delete a webhook
$result = $client->delete('/:webhooks/{id}', array(
    'id' => '<webhook id>'
));
// Create a webhook
client.post('/:webhooks', { 
    api: '<webhook api>',
    events: '<webhook events>',
    url: '<webhook url>',
    ...
}, function(result) {
    ...
});

// Retrieve a webhook
client.get('/:webhooks/{id}', { id: '<webhook id>', ... }, function(result) {
    ...
});

// Update a webhook
client.put('/:webhooks/{id}', { id: '<webhook id>', ... }, function(result) {
    ...
});

// Delete a webhook
client.delete('/:webhooks/{id}', { id: '<webhook id>' }, function(result) {
    ...
});
# Create a webhook
curl -X POST https://api.schema.io/:webhooks \ 
    -d 'api=<webhook api>' \ 
    -d 'events=<webhook events>' \ 
    -d 'url=<webhook url>' \ 

# Retrieve a webhook
curl -G https://api.schema.io/:webhooks/{id} \
    -d 'id=<webhook id>' \

# Update a webhook
curl -X PUT https://api.schema.io/:webhooks/{id} \
    -d 'id=<webhook id>' \

# Delete a webhook
curl -X DELETE https://api.schema.io/:webhooks/{id} \
    -d 'id=<webhook id>' \
Webhook Fields
alias
Alias used to refer to the webhook configuration
string
api string Required
Format (slug)
attempts_failed int
client_id string Format (slug)
date_created date Auto
date_final_attempt
Webhook to be disabled 7 days after the first failed attempt
date Formula if(date_first_failed, date(date_first_failed) + 604800000, null)
date_first_failed date
date_updated date Auto (update)
enabled bool
events array Required
id objectid
url string Required
Format (url)

Questions?

Join the community or contact us.