SAM API version 2
Welcome to the SAM APIv2
The documents can be accessed at https://apiv2docs.sam.org.au
These documents list all the endpoints on the left.
Clicking one of these will take you to the details for that endpoint and shows if it’s a GET, POST or PUT.
Below are a couple of examples of endpoints.
Useful Information
Two-way Communication - please be aware that you are now able to send sales that are created in an online store back to the art centre’s SAM Database. If you plan to use the SAM two-way communication component - please ensure that the art centre manager is aware that sales may be automatically generated in SAM based on those online sales. The online store sale prices can also override the prices in SAM if using the two-way communication. Scroll down to the bottom to find out.
GST – Items retrieved from the SAM API (Artworks & Prints) will display three prices. An exGST value, a GST amount and a Total price. GST is based on a number of factors. Some items will have GST applied, whereas others will not. In the case of items that do not have GST, the exGST will be the same as the Total, and the GST amount will be 0
Prints – Prints within SAM can have editions that effectively mean the same print/artwork appears as multiple records in SAM. The API will only return a maximum of one record for each edition. If an edition has multiple webactive prints then only 1 of these prints will be returned by the API. Once this is sold, the next print will appear in the edition until all webactive prints have been sold. A/P or P/P prints will show as a separate artwork in the online store.
Collaborations: - As with prints, collaborations are represented in SAM as multiple records, each with an individual artist and price. When returned via the API, these records will show as 1 artwork, the code will be eg. 24-20, though in SAM 24a-20 & 24b-20. In order to make a collaboration webactive, only one of the artworks in SAM needs to be webactive, however there is no issue with more than one being webactive. As long as one of the component artworks is webactive, all component artworks will be combined into a single artwork, tallying the price of all component artworks, and adding all artists to an array or artists that will be returned by the api. See the bottom of this document for more details.
Access Keys - these are the keys that are specific to an individual art centre’s data. If you need an access key to be deleted please contact support@sam.org.au.
Product variations - SAM has recently added the ability to enable variations for products. This will allow SAM Clients to create multiple variations of a product without having to create a separate product for each variant. Each variant has a description and its own stock levels and availability (status). Scroll down to Get/Store/Products to find out more.
Storing customer addresses in the SAM Database via the SAM API - see the bottom of this document for details.
Payments - The SAM APIv2 allows for the posting of sales into the SAM database - see the bottom of this document for details.
- Filtering Criteria - what determines whether a product or an artwork comes through the API:
o C - Consignment
o A - Artist Stock
o T - Stock
o S - Sold
The artwork / product also needs to have the WebActive field set to true.
Webhooks are available to be used once the APIv2 is set up. This allows online stores to have the functionality of webhooks to update their product and artwork quantity. With products on each change of stock level the webhook will update your shop with the new level. With artworks the level is changed from 1 for available online to 0 for not available. These are used when SAM sells the artwork or staff change webactive off. More Information.
Choosing The Right API:
The top of the document allows you to specify either the LIVE (https://sam.org.au) or test SAM (https://test.sam.org.au) version of the API.
This is important. Access keys are issued for a specific Art Centre. This Art Centre will either be in the SAM Live database or the SAM testing database.
If using a key for an Art Centre in the LIVE database, you will need to use the LIVE api.
If using a key for an Art Centre in the TEST database, you will need to use the TEST api.
This also applies to all request made through means other than the documentation site.
Authentication:
The next section of the doc provides a place to add authorisation. Doing this allows you to actually hit the api endpoints directly form the documentation and request data. These requests will be processed the same as any other request made to the API.
If you are using an access token (as opposed to getting a user token) you will need to set the authorisation type to Bearer.
Basically this means you will need to fill this field in as Bearer ********* (where ******* is the key that you have been provided).
After entering the Authorisation and clicking set, it should look something like the below screenshot.
Using Endpoints:
Eg. Clicking on the Store:Artist “Get a list of artists” looks like the screenshot below.
The top line is the name of the endpoint. And the next line shows if it’s a GET, POST or PUT. (In this case it’s a GET endpoint) The second line also shows the URL to the endpoint.
So to access this endpoint, I need to send a GET request to https://apiv2.sam.org.au/store/artists.
The next section lists any query string or path parameters. For some endpoints these are mandatory, some they are optional, and others they are not available.
In this case nothing is needed (I’ll give another example that does require this, further down in these instructions.
Below this is the authorisation details as well as the option to run the query if authorisation has been provided.
So the above screenshot shows that I have added an API Key (Authorisation) in header. If I had not applied a key at the top of the page, it would display "No API key applied"
By having a Key setup, I can hit the TRY button to actually make the request with my API key.
Before I hit the TRY button, the response below will show example data. It shows the Schema (structure) of what keys and values will be returned.
Clicking the EXAMPLE tab will give me an example data set.
Because I have added an auth key, I can click the TRY button. This will then make the request for my actual data from my art centre.
Doing this, an actual response appears above the example response.
This response c contains data from my art centre. It also lists the Response headers if I click on the tab
I can also get a complete CURL request by clicking the CURL tab. (I have blurred the Authorisation Key in the below screenshot)
As mentioned above, some endpoints will require parameters to be passed.
Eg Clicking on the Store:Artist “Get an artists details” look like the screenshot below.
This is similar to getting the list of artists, but this request requires an id parameter which needs to be the id of the artist that you want details for.
So looking at our artist list endpoint, we can see that one of our artists had the id 1235784
If we enter that id into the id field and click TRY we get the following response: And we can see from the CURL tab the corresponding CURL request.
GET /store/products
This endpoint returns a list of all available products for the authenticated Art Centre.
Product variations are not returned in this endpoint, however each product will have a count of the number of different variations available. It is also worth noting that products with variations will return a stock Quantity of 0 as each variation will have it’s own stock quantity.
The truncated JSON below shows the Quantity and VariationCount variables as they will appear for a product with available variants.
{
"Id": 4438,
"Status": "A",
"Description": "Test with three variation types",
"Quantity": 0,
"Price": 110,
"Name": "Test Shirt - V Size, Colour, Gender",
….
"VariationCount": 4,
"SAMCategoryId": 1458,
"SaleAmount": 110,
"GST": 10,
"ExGST": 100,
"HasVariationStock": true
}
GET /store/product/{id}
This endpoint will return the full details for an individual product. This will include further details about all the available variants or the product.
The truncated JSON below contains a sample of the information available for variations.
There are three main areas of concern.
1. The HasVariationStock key, which is a flag which determines if any of the variants have stock. If no variants have available stock, then this key will be false, otherwise it will true.
2. The VariationTypes array. This array lists all the possible variations and all the possible options for that variation type.
In the example JSON below, the variation types are Size, Colour, Gender and Other. These are specified in the SAM Portal. These VariationTypes can be used to define the necessary selectors within a shop webpage. Eg, These would most like each represent a different <select> element.
Each VariationType has an array of possible options. These represent the options that should be made available in each selection element.
3. The Variations.
These are the actual combinations that have been entered in the SAM Portal.
{
"Id": 4438,
"Status": "A",
"Description": "Test with three variation types",
"Quantity": 0,
"Price": 110,
"Name": "Test Shirt - V Size, Colour, Gender",
….
"PurchasedByArtCentre": true,
"VariationCount": 4,
"SAMCategoryId": 1458,
"SaleAmount": 110,
"GST": 10,
"ExGST": 100,
"HasVariationStock": true,
"VariationTypes": [
{
"Id": 1,
"Description": "Size",
"Options": [
"Large",
"Small"
]
},
{
"Id": 2,
"Description": "Colour",
"Options": [
"black",
"blue"
]
},
{
"Id": 3,
"Description": "Gender",
"Options": [
"Female",
"Male"
]
},
{
"Id": 4,
"Description": "Other",
"Options": [
]
}
],
"Variations": [
{
"ProductVariantDescription": "Large black Female",
"ProductVariantQty": 5,
"ProductVariantStatus": "A",
"ProductVariationId": 197,
"VariationOption1": "Large",
"VariationOption3": "Female",
"VariationOption2": "black"
},
{
"ProductVariantDescription": "Large black Male",
"ProductVariantQty": 5,
"ProductVariantStatus": "A",
"ProductVariationId": 198,
"VariationOption1": "Large",
"VariationOption3": "Male",
"VariationOption2": "black"
},
{
"ProductVariantDescription": "Small black Female",
"ProductVariantQty": 5,
"ProductVariantStatus": "A",
"ProductVariationId": 199,
"VariationOption1": "Small",
"VariationOption3": "Female",
"VariationOption2": "black"
},
{
"ProductVariantDescription": "Small blue Male",
"ProductVariantQty": 5,
"ProductVariantStatus": "A",
"ProductVariationId": 200,
"VariationOption1": "Small",
"VariationOption3": "Male",
"VariationOption2": "blue"
}
]
}
IMPORTANT NOTE for Product Variations
The SAM Portal does not enforce any logic rules around what combinations a user can specify when creating product variations. Therefore, it is possible that a user may create variation combinations that are illogical.
Using the example of a T-shirt, it is possible for a user to include the VariationTypes of Size, Colour and Gender. That user could then create variations such as:
Large Male,
Small Blue,
Large Red Female
Large Green
Green
As these are all considered valid within the SAM Portal, they will all be returned by the API in the Variations Array.
Ideally these should not be created in this way, but is left to the end user to correct this should it occur.
At this stage, product variations do not allow for individual images to be added specific to that variant, but this may be added at a later stage.
Two Way Communication
Some considerations need to be made if you are planning to send sales information back into the SAM Database.
- Sale - Invoice with payment. Sending the information back into SAM with the invoice with payment will allow it to record any notes or URL links you need to payment information in external websites (eg stripe payment link).
- Shipping -
- Most art centres have a ‘Freight’ category where shipping costs are recorded against when sent back into SAM.
- All costs need to have ‘Sale Amount’, ‘ExGST’, ‘Quantity’, ‘Total cost’ recorded
3. Products - ‘Sale Amount’, ‘ExGST’, ‘Quantity’, ‘Total cost’ and SAM Category ID (category type for the product in SAM) and Title.
4. Artwork
- ‘Sale Amount’, ‘ExGST’, ‘Quantity’, ‘Total cost’
5. Donations
Donations can be set up in SAM as a category that has no GST. If the art centre is registered with DGR (Deductible Gift Recipient status) then they can have GST Free donations made and recorded into SAM.
6. Gift Vouchers or Discounts
Discounts need to be made off all items. The total discount will need to be applied across the items in the sale so that the total price reflects the discount amount.
Storing customer addresses in the SAM database via the SAM API.
SAM stores addresses differently for international addresses compared to Australian addresses. The following applies for both the billing address and the shipping address.
If you are posting an Australian address:
Sam stores Australian addresses using IDs for the suburb and state as well as the country code.
So to store an Australian Address in SAM, there are 4 relevant fields.
Address - This is usually a street address (eg 13 Smith St )
SuburbId - This needs to be a numeric ID that represents the suburb. These IDs can be obtained from the API using the /store/address/suburbs
StateId - This needs to be a numeric ID that represents the state. These IDs can be obtained from the API using the /store/address/states
CountryId - This needs to be a numeric ID that represents the country. These IDs can be obtained from the API using the /store/address/countries For Australia this is 14
The API, however has some additional fields including unit, streetNumber and postCode. This is for compatibility with other systems.
When passing an address, you can choose to use the unit and streetNumber fields, or omit these.
The API will ultimately take the content of the unit, streetNumber and address fields and concatenate them together to store un the address field in the SAM database.
The postCode field is also optional and can be omitted for Australian Addresses as the postcode will be extracted from the City id.
When posting an address that uses the country code 14 (Australia), the city and state objects must contain valid ids.
"shippingAddress": {
"unit": "",
"streetNumber": “13",
"address": "Smith St",
"postCode": "2602",
"city": {
"id": 121
},
"state": {
"id": 1
},
"country": {
"id": 14
}
If you are posting an international address:
Sam stores International addresses differently to Australian Addresses.
Because SAM doesn’t have a list of suburb/city or state ids for the whole world, it doesn’t use ids for these data points.
Instead, the address is stored as a single text string and then a country code.
In the example below, the country id is 27 (Bolivia) so the entire content of the unit, streetNumber, address, postCode, city and state fields will all be concatenated together to store the address as:
12, Smith St, Westhaven 87352, Georgia
"shippingAddress": {
"unit": "",
"streetNumber": “12 ",
"address": “Smith St",
"postCode": “87352",
"city": {
"title": “Westhaven"
},
"state": {
"title": “Georgia"
},
"country": {
"id": 27
}
},
You can also choose to leave most of these fields blank and just send an address and country if you prefer. This gives you full control over the address formatting.
"shippingAddress": {
"address": “12 Smith St, Westahven Georgia 87352”,
"country": {
"id": 27
}
}
Posting multiple payments with sales.
The SAM APIv2 allows for the posting of sales into the SAM database. When posting a sale, payment details are required to indicate how the sale was made.
Payments are posted as an array to allow for sales with multiple payment types when a sale is split across multiple payment methods.
Only one payment item is required in the array, however, any number of additional payments can be included.
Payment items within the payments array consist of three component kay pairs:
The paymentType key is a single character string which indicates the method of payment (eg Cash, Visa, etc). These codes can be obtained using the /store/payment-types endpoint.
The paymentNotes key is an optional string which can be used to store a short note about the payment.
The total key is an integer which indicates how much of the total sale (in dollars) was paid by this payment method.
The combined total of all payments within the array must add up to the total of the sale. There is currently no facility to allow for partial payments to be made. The API will validate that these values add to match the total and will return an error message if they do not.
An example of payment info included in a sale:
Note that this is only a subset of a sale with the key values relating to payments.
….
"total": 100,
"shipping": 20,
"payments":[
{
"paymentType": "C",
"paymentNotes": “Partial cash payment",
"total": 40
},
{
"paymentType": "G",
"paymentNotes": “Payment using gift voucher",
"total": 60
}
],
…..
For backwards compatibility, there is also the option, when posting a single payment method, to just add a single paymentType and paymentNotes pair, and exclude the payments array.
In this instance the value of the payment is assumed to be the total of the sale.
We recommend using the payments array method for greater flexibility and consistency, however if you have only a single payment method then the two following examples are interchangeable.
"total": 100,
"shipping": 20,
"paymentType": "S",
"paymentNotes": “A single payment",
Is actually equivalent to
"total": 100,
"shipping": 20,
"payments":[
{
"paymentType": “S",
"paymentNotes": “A single payment",
"total": 100
}
],
Collaborative Artworks
SAM treats collaborative works as multiple related art works.
As an example, if a painting is a collaboration between three different artists, SAM treats these as three separate artworks, each by one of the collaborating artists.
Usually you would not want to present these separate artworks as different items (we would not want to have the item show up as three separate paintings in a store), so when you request your art centre's artworks, the API will return this collaboration as a single item, with three artists associated with it.
The artwork will have an ArtistId associated with it as well as an array of associated Artists. The ArtistId is for consistency and backwards comparability and will be one of the artists in the Artists array.
Collaborations will also have a CollabId value. Other non collaborative artworks will have a null for this value.
Updated 29th March 2023