This is a guide for web developers who are using SAM API v3 to connect an art centre's web store to SAM v2, allowing the artworks, editions and products catalogued in SAM to be sold online, and have the sales and inventory changes automatically show up in SAM when an online sale is made.
The information in this guide describes how to use the API itself, and should be used in conjunction with the API documentation which specifies available endpoints, parameters, request and response bodies.
If you are looking for help using SAM itself, please consult the SAM knowledge base, or contact the SAM team for support.
Table of Contents
Accessing SAM API v3
To log in to the SAM API, you will need to first request an API login if you have not already done so. Once you have a login, the interactive API documentation can be used to get familiar with the API and make test API calls to better understand how it works.
Migrating from SAM v1?
SAM API v3 was introduced to support the new features and different requirements of SAM v2. While SAM API v3 is based on the old SAM API v1/v2, it introduces incompatible changes with those earlier versions, and integrations written to work with them will need to be fully updated to work with SAM API v3.
Note that when art centres migrate from SAM v1 to v2, they will also need to migrate from SAM API v1/v2 to v3 at the same time. The old APIs will stop working for them when they migrate.
Web Developer's Guide
Authentication
Use the authentication endpoints to generate tokens required by all other API endpoints.
The login endpoint returns a new, short-lived access token used for making other API calls, and a longlived refresh token.
The refresh token can be used to generate new access tokens when they expire, without needing authentication details.
Common API parameters
These identifiers differ between different art centres, and typically need to be looked-up in the API then cached for re-use.
Shipping Category ID – This denotes the AC Shipping sub category. Check whether a shipping sub category exists, or set one up under freight/packing. Use the API category list to find its ID to set this value.
Sales Factor ID – This differs by art centre, so it needs to be set accordingly. Web devs can find this information from the API for any artwork or product. An art centre will only have one ID.
Staff Store ID – This is a required field in create sale, but it can be set to any number. (It is a legacy field).
OTHER SER category – Set up any other sub categories you may need to take payments or goods/services offered by the art centre, such as donations, gift vouchers as sub categories. These can be paid via “OTHER” in createSale.
Categories
- There are no longer web categories in new SAM.
- Categories are now broken into Parent Categories, which are standard across all Art centres and Sub categories, which are customisable by individual Art centres.
- Categories are broken into Inventory types, Artwork, Edition, Product and Other.
- Other is where Categories that are “Service” items live, such as fees, shipping, framing, donations etc. You cannot attach inventory to these categories, but you can pay directly into the categories in a sale.
Categories in new SAM:
Paying to 'Other' Categories via the API:
You can access Categories via store-category-controller
In getCategory, each category has an `Id` and a `ParentID`, so you can sort sub categories into Parent Categories.
If `ParentID` is null, it is the Parent Category, where a category has a `ParentID` it is a sub category
Example
getCategorylist
"Id": 1057,
"ItemCount": 38,
"ArtworkCount": 38,
"ProductCount": 0,
"ChildCount": 4,
"ArtCentreId": 9,
"Title": "Painting",
"ParentId": null,
"ImageURL": "",
"Weight": 1
},
{
"Id": 1058,
"ItemCount": 30,
"ArtworkCount": 30,
"ProductCount": 0,
"ChildCount": 0,
"ArtCentreId": 9,
"Title": "Paintings",
"ParentId": 1057,
"ImageURL": "",
"Weight": 1
getArtworklist
"DeceasedDate": "",
"Categories": [
{
"Id": 1057,
"Title": "Painting"
}
],
"SubCategories": [
{
"Id": 1058,
"Title": "Paintings"
}
Shipping
To send shipping back to SAM so it appears in the SAM sale and receipt,
Recommended method for paying shipping is to do it through OTHER [ ] in create sale, so you can send ex gst and SaleAmount. Sending it via Shipping is currently not working correctly and needs to be fixed in API
Before doing this, check that the Art centre has set up a sub category for shipping set up in other.
Under the parent category Freight/Packing, specify which to use for online shipping.
To find the correct category number for the art centres Other category Id, use getCategory to locate the ID. (You should find it listed under parent category Freight/Packing).
The sub category ID will be unique to each Art centre.
{
"Id": 6011,
"ItemCount": 0,
"ArtworkCount": 0,
"ProductCount": 0,
"ChildCount": 2,
"ArtCentreId": 17,
"Title": "Freight/Packing",
"ParentId": null,
"ImageURL": "",
"Weight": 1
},
{
"Id": 6012,
"ItemCount": 0,
"ArtworkCount": 0,
"ProductCount": 0,
"ChildCount": 0,
"ArtCentreId": 17,
"Title": "Shipping",
"ParentId": 6011,
"ImageURL": "",
"Weight": 1
},
Then to send, add to your shipping into payload here
"others": [
{
"ExGST": 9.09,
"CategoryId": 10584,
"SaleAmount": 10
}
],
Address Lookup
Currently there are some workarounds required to get the customer's shipping address and billing address from Shopify or WordPress into SAM and formatting correctly. Please use the workaround below.
address1: "5 Sydney Customs House" address2: 'Unit 3' city: "Sydney" state: "New South Wales" zip: "2000" country: "Australia"
Before making the createSale call, we create a single address line using:
single_address_line = address1 + city + state + zip
Then, assign that value to shippingAddress.address.
and the final address payload is as below.
-
unit←address2 streetNumber: ''-
address:single_address_line postcode: zip-
city: {city.id, city.title} -
state: {state.id, state.title} -
country: {country.id, country.title}
Image Sizes
The API is designed to allow devs to retrieve images at set sizes across all inventory.
-
The Original size of the image as stored in SAM
- 2048 Pixels wide
- 1024 Pixels wide
- 120 Pixels wide
This is in the dev queue to be fixed. An eta is not available.
Until it is fixed it is advised that images on SAM are sized as the following, otherwise they will be ignored and wont be processed by the plugins and be visible on shopify/WP.
Original Artwork images uplaoded to SAM should be within these limits
File size: 20 MB maximum.
Resolution: 25 megapixels maximum (approximately 5000 × 5000 px).
Shopify supports a maximum image size of 5000 × 5000 pixels (up to 25 megapixels), images larger than that will be ignored on import.
Discount
There is a new Discount function in SAM. Art centres can setup discounts in SAM. These can be % or $ amounts and be applied to the entire sale or particular inventory types /items (artists, everything, item types – artworks, products, editions, or categories).
They can have codes or not have codes, and they can have expiry dates set.
See for more info https://help.sam.org.au/hc/en-au/articles/40119700476953-How-to-apply-a-Discount
https://apiv3.sam.org.au/#/operations/getDiscountList
Expiry on Discounts
When applying an expired discount code:
- The sale is still processed without a discount applied
- After executing the createSale API, the sale information and a message about the discount is displayed.
Example RESPONSE:
{
"Id": 831308,
"CustomerOrSellerId": 1,
"TotalSaleAmount": 3192.5,
"ReferenceNo": "2342314",
"Message": "The discount code has expired and cannot be applied: per25"
}
When applying a valid discount code:
- The sale is processed with a discount applied
- After executing the createSale API, the sale information and an empty message is displayed.
Example RESPONSE:
{
"Id": 831309,
"CustomerOrSellerId": 1,
"TotalSaleAmount": 3192.5,
"ReferenceNo": "2342314",
"Message": ""
}
Discounts API
There are 2 types of discount
[Type 1: apply a discount with discountCode]
{
"id": 12,
"discountName": "fixed30",
"discountCode": "thirty",
"discountType": "fixed",
"discountAmount": 30.0,
"discountedItem": {
"id": 12,
"appliesTo": "everything",
"discountItemTypes": null
}
}
In the payload of createSale, it is required to have both the information of discountName and discountCode in the payload object discount
"discount": {
"discountName": "fixed30",
"discountCode": "thirty"
},
In this case, both discountName and discountCode will be checked to see if they match a certain discount.
[Type 2: apply a discount that does not have discountCode]
{
"id": 11,
"discountName": "per25",
"discountCode": null,
"discountType": "percentage",
"discountAmount": 25.0,
"discountedItem": {
"id": 11,
"appliesTo": "everything",
"discountItemTypes": null
}
},
In the payload of createSale, it is only required to have discountName in the payload object discount
"discount": {
"discountName": "per25"
},
In this case, even if the user puts the discountCode in, the discountCode will be ignored. In other words, only the discountCode is checked.
There are 2 ways to apply the discount to sale:
[Case 1: Apply discount to the whole sale]
Example payload:
{
"customer": [
{
"firstName": "Audra",
"lastName": "Waters",
"contactName": "Audra Waters",
"shippingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"billingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"phone": "0410876726",
"mobile": "0410876726",
"email": "audrawaters@test.com",
"billingPhone": "string",
"billingMobile": "string",
"shippingEmailAddress": "audrawaters@test.com",
"note": "string"
}
],
"artworks": [
{
"Id": 290346,
"ExGST": 1600,
"SaleAmount": 1600
],
"products": [
{
"Id": 49875,
"ProductVariationId": 55075,
"ExGST": 50,
"Quantity": 2,
"SaleAmount": 55
}
],
"others": [
{
"CategoryId": 5297,
"ExGST": 100,
"SaleAmount": 110
}
],
"discount": {
"discountName": "fixed30",
"discountCode": "thirty"
},
"shipping": 50,
"shippingCategoryId": 5268,
"total": 16212,
"storeStaffId": 1,
"ref": "asf",
"ref_no": "2342314",
"saleNotes": "asdf",
"paymentType": "CASH",
"paymentNotes": "test",
"payments": [
{
"paymentType": "CASH",
"paymentNotes": "test",
"total": 16212
}
],
"receiptNo": "REF223414",
"purchaseOrder": "test",
"paymentTerms": 15,
"salesFactorId": 1
}
In this case, the discount will be applied to every artwork, product and edition item in the sale. The discount will not be applied to other SER-item.
[Case 2: Apply discount to certain items]
Example payload
{
"customer": [
{
"firstName": "Audra",
"lastName": "Waters",
"contactName": "Audra Waters",
"shippingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"billingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"phone": "0410876726",
"mobile": "0410876726",
"email": "audrawaters@test.com",
"billingPhone": "string",
"billingMobile": "string",
"shippingEmailAddress": "audrawaters@test.com",
"note": "string"
}
],
"artworks": [
{
"Id": 290346,
"ExGST": 1600,
"SaleAmount": 1600
],
"products": [
{
"Id": 49875,
"ProductVariationId": 55075,
"ExGST": 50,
"Quantity": 2,
"SaleAmount": 55,
"discount": {
"discountName": "per25"
},
}
],
"others": [
{
"CategoryId": 5297,
"ExGST": 100,
"SaleAmount": 110
}
],
"shipping": 50,
"shippingCategoryId": 5268,
"total": 16247.5,
"storeStaffId": 1,
"ref": "asf",
"ref_no": "2342314",
"saleNotes": "asdf",
"paymentType": "CASH",
"paymentNotes": "test",
"payments": [
{
"paymentType": "CASH",
"paymentNotes": "test",
"total": 16247.5
}
],
"receiptNo": "REF223414",
"purchaseOrder": "test",
"paymentTerms": 15,
"salesFactorId": 1
}
For instance, after the above payload is executed, the discount is applied only to product variant 55075.
EXTRA NOTE: The payload's total and the payload's payments total
The value of the payment total would be stored as sales_receipt_header.total_paid and sales_receipt_detail.amount.
The value of the total includes the items' amount (with quantity), GST, and discount. In other words, the payload's total value is the Total (inc. GST) in the SAM system (below picture).
For further information of calculation logic, please refer to SAM's calculation logic.
Donations
Donations can be made against the donations sub category, using any value entered by the user.
To receive payment for a donation, use createSale ‘Others’ inventory and nominate the donation sub-category via the API, enter the $ value into “SaleAmount” and “ExGST” the sub category ID for gift voucher in “CategoryId”
Before doing this, check that the Art centre has set up a sub category in OTHER, under the parent category DONATION, and add a sub category for donations. Ensure the category is marked as 'no GST'. Note: you must create a sub category, payments can’t be made into the Parent Category.
"others": [
{
"CategoryId": 0,
"ExGST": 0,
"SaleAmount": 0
}
To find the correct category number for the art centres Donation sub category CategoryId, use getCategory to locate the ID (You should find it listed under the parent category DONATION)
The sub category ID will be unique to each Art centre.
{
"Id": 6011,
"ItemCount": 0,
"ArtworkCount": 0,
"ProductCount": 0,
"ChildCount": 2,
"ArtCentreId": 17,
"Title": "Donation",
"ParentId": null,
"ImageURL": "",
"Weight": 1
},
{
"Id": 6012,
"ItemCount": 0,
"ArtworkCount": 0,
"ProductCount": 0,
"ChildCount": 0,
"ArtCentreId": 17,
"Title": "Donations",
"ParentId": 6011,
"ImageURL": "",
"Weight": 1
},
Gift voucher
Payment by Gift voucher
The APIv3 can accept a gift voucher as a payment type. But there is nowhere in SAM that tracks vouchers, unique voucher numbers, or voucher values, so you may not wish to allow gift voucher payments online, as you won't necessarily be able to verify them without a third-party system.
https://new.webapi.sam.org.au/store/payment-types
Retrieves a list of all available payment types supported by the store.
Purchase of a gift voucher
Purchases can be made against the gift voucher category, using any value entered by the user. However, SAM does not have the capability to manage gift voucher IDs, etc, so this needs to be done manually outside of SAM by the art centre.
To receive payment for a gift voucher, use createSale ‘Others’ inventory and nominate the gift voucher sub-category via the API, enter the $ value into “SaleAmount” and “ExGST”, and the sub category ID for gift voucher in “CategoryId”
Before doing this check that the Art centre has set up a sub category in OTHER, under the parent category GIFT VOUCHER, and add a sub category for gift vouchers. Note: you must create a sub category, payments can’t be made into the Parent Category.
"others": [
{
"CategoryId": 0,
"ExGST": 0,
"SaleAmount": 0
}
To find the correct category number for the art centres gift voucher sub category CategoryId, use getCategory to locate the ID (You should find it listed under the parent category Gift Voucher)
The sub category ID will be unique to each Art centre.
{
"Id": 6011,
"ItemCount": 0,
"ArtworkCount": 0,
"ProductCount": 0,
"ChildCount": 2,
"ArtCentreId": 17,
"Title": "Gift Voucher",
"ParentId": null,
"ImageURL": "",
"Weight": 1
},
{
"Id": 6012,
"ItemCount": 0,
"ArtworkCount": 0,
"ProductCount": 0,
"ChildCount": 0,
"ArtCentreId": 17,
"Title": "Gift Card",
"ParentId": 6011,
"ImageURL": "",
"Weight": 1
},
OTHER payload and scenarios
SCENARIO 1:
- Apply a fixed discount of $30 to wholesale
- 1 artwork
- 1 product with quantity of 2
- 1 other item
- 1 shipping item
PAYLOAD:
createSale
{
"customer": [
{
"firstName": "Audra",
"lastName": "Waters",
"contactName": "Audra Waters",
"shippingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"billingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"phone": "0410876726",
"mobile": "0410876726",
"email": "audrawaters@test.com",
"billingPhone": "string",
"billingMobile": "string",
"shippingEmailAddress": "audrawaters@test.com",
"note": "string"
}
],
"artworks": [
{
"Id": 290346,
"ExGST": 16000,
"SaleAmount": 16000
}
],
"products": [
{
"Id": 49875,
"ProductVariationId": 55075,
"ExGST": 50,
"Quantity": 2,
"SaleAmount": 55
}
],
"editions": [],
"others": [
{
"CategoryId": 5297,
"ExGST": 100,
"SaleAmount": 110
}
],
"discount": {
"discountName": "fixed30",
"discountCode": "thirty"
},
"shipping": 50,
"shippingCategoryId": 5268,
"total": 16212,
"storeStaffId": 1,
"ref": "asf",
"ref_no": "2342314",
"saleNotes": "asdf",
"paymentType": "CASH",
"paymentNotes": "test",
"payments": [
{
"paymentType": "CASH",
"paymentNotes": "test",
"total": 16212
}
],
"receiptNo": "REF223414",
"purchaseOrder": "test",
"paymentTerms": 15,
"salesFactorId": 1
}
completeSale:
{
"Id": 134241,
"artworks": [
{
"Id": 290346,
"ExGST": 16000,
"SaleAmount": 16000
}
],
"products": [
{
"Id": 49875,
"ProductVariationId": 55075,
"ExGST": 50,
"Quantity": 2,
"SaleAmount": 55
}
],
"editions": [
],
"others": [
{
"CategoryId": 5297,
"ExGST": 100,
"SaleAmount": 110
}
],
"discount": {
"discountName": "fixed30",
"discountCode": "thirty"
},
"shipping": 50,
"shippingCategoryId": 5268,
"CustomerOrSellerId": 1,
"TotalSaleAmount": 16212,
"payments": [
{
"paymentType": "CASH",
"paymentNotes": "test",
"total": 16212
}
],
"ReferenceNo": "2342314"
}
Actual Result:
Creating the sale using the SAM System:
Creating the sale using APIV3:
SCENARIO 2:
- Apply discount percentage 25% to product item
- 1 artwork
- 1 product with quantity 2
- 1 other item
- 1 shipping item
PAYLOAD:
createSale
{
"customer": [
{
"firstName": "Audra",
"lastName": "Waters",
"contactName": "Audra Waters",
"shippingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"billingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"phone": "0410876726",
"mobile": "0410876726",
"email": "audrawaters@test.com",
"billingPhone": "string",
"billingMobile": "string",
"shippingEmailAddress": "audrawaters@test.com",
"note": "string"
}
],
"artworks": [
{
"Id": 290346,
"ExGST": 16000,
"SaleAmount": 16000
}
],
"products": [
{
"Id": 49875,
"ProductVariationId": 55075,
"ExGST": 50,
"Quantity": 2,
"SaleAmount": 55,
"discount": {
"discountName": "per25"
}
}
],
"editions": [
],
"others": [
{
"CategoryId": 5297,
"ExGST": 100,
"SaleAmount": 110
}
],
"shipping": 50,
"shippingCategoryId": 5268,
"total": 16247.5,
"storeStaffId": 1,
"ref": "asf",
"ref_no": "2342314",
"saleNotes": "asdf",
"paymentType": "CASH",
"paymentNotes": "test",
"payments": [
{
"paymentType": "CASH",
"paymentNotes": "test",
"total": 16247.5
}
],
"receiptNo": "REF223414",
"purchaseOrder": "test",
"paymentTerms": 15,
"salesFactorId": 1
}
completeSale:
{
"Id": 134241,
"artworks": [
{
"Id": 290346,
"ExGST": 16000,
"SaleAmount": 16000
}
],
"products": [
{
"Id": 49875,
"ProductVariationId": 55075,
"ExGST": 50,
"Quantity": 2,
"SaleAmount": 55,
"discount": {
"discountName": "per25"
}
}
],
"editions": [
],
"others": [
{
"CategoryId": 5297,
"ExGST": 100,
"SaleAmount": 110
}
],
"shipping": 50,
"shippingCategoryId": 5268,
"CustomerOrSellerId": 1,
"TotalSaleAmount": 16247.5,
"payments": [
{
"paymentType": "CASH",
"paymentNotes": "test",
"total": 16247.5
}
],
"ReferenceNo": "2342314"
}
Actual Result:
Creating the sale using the SAM System:
Creating the sale using APIV3:
Inventory
All Inventory (Artworks, Editions, Products) items that are toggled to online store in SAM will appear through APIv3. This allows art centres to show items of different availability – out of stock, sold, etc, even when they are not available for sale. Art centres should use the toggles to control what appears on their website, rather than relying on an item being sold or out of stock to make it disappear.
Statuses
More info about the status you can expect for each inventory type is below.
Parent products (ProductStatus - Available / Not available)
- If a product has been ticked online on SAM and has stock, its status via the API will be available
- If a product has been ticked online on SAM and is out of stock, its status via the API will be not available
- If a product has been ticked online on SAM and has variations with a mix of status, eg, out of stock, available, low stock (on SAM at the parent product level, the status is listed as mixed), its status via the API will be available.
- If a product is not ticked online in SAM, it will not appear on the API get requests.
Product variations (VariationStatus - Available / Not available)
- If a variation, parent product has been ticked online on SAM and the variation has stock, its VariationStatus via the API will be available.
- If a variation's parent product has been ticked online in SAM and the variation is out of stock, the variation's VariationStatus via the API will be not available.
Artworks (ArtworkStatus - Sold / Available)
- If an artwork has been ticked online on SAM and is available for sale, its status via the API will be available.
- If an artwork has been ticked in SAM and sold, its status via the API will be SOLD.
Note: Other statuses are available, including collections, consignment, and missing. Typically, these artworks should not appear in the store and definitely can't be sold. (In future, these may be used if an art centre wants to showcase their collection online, but these would not be for sale.)
Pagination
Pagination in APIv3 is limited to ensure art centres don’t overload the call
Artworks / Products / Editions / Artists
-
Limit and Page parameters are now mandatory. 100 is the maximum limit per call.
Prices & GST
Are shared as
- SaleAmount
- GST
- ExGST
SaleAmount includes GST where GST occurs. Not all items have GST, so you need to use the GST and Ex GST to know if something has GST.
As there may be some items that aren't GST – GST calculation must be the sum of the GST Amounts, and on a per-item basis, not a flat 10% on the total. (Can be based on whether the artist is registered for tax).
So you must look at SaleAmount, GST and ExGst to work this out.
Sales process
To successfully complete a sale, follow the steps below:
Create sale
- Your webstore calls the APIv3 “createSale” endpoint. (Note: Set the `SaleAmount` using the price retrieved from the getList or get APIs. Use the corresponding `salesFactorId` (mandatory) as well.)
- If the customer hasn’t paid in full, SAM holds the order as a draft invoice.
Display offline payment instructions – website handles payment
- Based on the payment method you’ve chosen, the webstore shows your customer how to transfer funds (e.g., bank transfer details).
Customer completes the transfer
- The customer sends the payment and receives a reference number from their bank.
Send confirmation of payment using Complete Sale
- Your webstore calls the APIv3 “completeSale” endpoint, passing the invoice ID and the bank’s reference number. (Note: Use the `Id` returned from the “createSale” API response as the `Id` value in the “completeSale” API.)
- SAM then converts the draft invoice into a receipt invoice, completing the order
storeStaffId – Is a required field - can be set to any number – just can’t be blank. (Can be set to 0).
purchaseOrder optional.
CustomerOrSellerID - Art Centre ID.
PaymentTerms – Needs to be set to 15 or 30, Passes Number of days you wish to wait for payment.
Please follow the example API sequence below to complete the sale process in the new SAM API V3:
createSale API
completeSale API
{
"customer": [
{
"firstName": "Audra",
"lastName": "Waters",
"contactName": "Audra Waters",
"shippingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"billingAddress": {
"unit": "unit1",
"streetNumber": "30",
"address": "Smith St",
"postCode": "3002",
"city": {
"id": 1,
"title": "fasdf"
},
"state": {
"id": 3,
"title": "string"
},
"country": {
"id": 1,
"title": "string"
}
},
"phone": "0410876726",
"mobile": "0410876726",
"email": "audrawaters@test.com",
"billingPhone": "string",
"billingMobile": "string",
"shippingEmailAddress": "audrawaters@test.com",
"note": "string"
}
],
"artworks": [
{
"Id": 2058105,
"ExGST": 3500,
"SaleAmount": 3500
}
],
"products": [],
"others": [],
"discount": {},
"shipping": 50,
"shippingCategoryId": 7071,
"total": 3550,
"storeStaffId": 18,
"ref": "asf",
"ref_no": "2342314",
"saleNotes": "asdf",
"paymentType": "CASH",
"paymentNotes": "test",
"payments": [
{
"paymentType": "CASH",
"paymentNotes": "test",
"total": 3550
}
],
"receiptNo": "REF223414",
"purchaseOrder": "test",
"paymentTerms": 15,
"salesFactorId": 313
}
Note: Set the `SaleAmount` using the price retrieved from the getList or get APIs. Use the corresponding `salesFactorId` as well.
Response looks like
{
"Id": 850929,
"CustomerOrSellerId": 18,
"TotalSaleAmount": 3550.0,
"ReferenceNo": "2342314",
"Message": ""
}
Copy “Id” from response and add to CompleteSale
ii. Sample Payload for completeSale API
{
"Id": 850929,
"artworks": [
{
"Id": 2058105,
"ExGST": 3500,
"SaleAmount": 3500
}
],
"products": [],
"editions": [],
"others": [],
"CustomerOrSellerId": 1,
"TotalSaleAmount": 3550,
"payments": [
{
"paymentType": "Credit Card",
"paymentNotes": "Payment pending - will be updated after successful transaction",
"total": 3550,
"discount":{
"discountCode": "TestingD8"
}
}
],
"ReferenceNo": "REF223429"
}
Note: Use the Id returned from the createSale API response as the Id value in the completeSale API.
Product Variations
Variations can now have different prices at the variation level.
Variations can have different images per variation level.
In new SAM when creating variations, VariationTypes are joined together into one field as the name of each variation (ProductVariantDescription)
VariationTypes are provided via the API, but would require a script to be built on the web side to break ProductVariantDescription apart.
It is therefore advisable that variations be displayed as a list of ProductVariantDescription. At this stage, we are not 100% if VariationTypes will migrate correctly across from old SAM. The logic of having Variations broken into types in SAM was not built in this version.No doubt this will be improved over time in future iterations of SAM. But for now, this is how it has been built, and we web devs will need to find a way to work with it.
Example
"VariationTypes": [
{
"Id": 1448,
"Description": "SIZE",
"Options": [
"0-3 Months",
"3-6 Months",
"6- 12 Months",
"12-18 Months",
"24 Months"
]
},
{
"Id": 1453,
"Description": "COLOUR",
"Options": [
"Light Grey"
]
},
{
"Id": 1454,
"Description": "OTHER",
"Options": [
"UNISEX"
]
}
"Variations": [
{
"ProductVariantDescription": "0-3 Months-Light Grey-UNISEX",
"ProductVariantQty": 10,
"ProductVariationId": 331283,
"Sku": "P2453915-1",
"SaleAmount": 25.00,
"GST": 2.27,
"ExGST": 22.73,
"VariationStatus": "Available",
"Images": [
{
"Id": 6756,
"variants": {
"Id": 1958370,
"VarientTypeId": 0,
"Title": "",
"Width": null,
"Cropped": 0,
"URL": "https://uat.webapi.sam.org.au/document/d0a15513-8c60-4695-a9d9-376685df2fc5.jpeg"
},
"default": true
}
]
},
{
"ProductVariantDescription": "3-6 Months-Light Grey-UNISEX",
"ProductVariantQty": 10,
"ProductVariationId": 331284,
"Sku": "P2453915-2",
"SaleAmount": 25.00,
"GST": 2.27,
"ExGST": 22.73,
"VariationStatus": "Available",
"Images": [
{
"Id": 6756,
"variants": {
"Id": 1958370,
"VarientTypeId": 0,
"Title": "",
"Width": null,
"Cropped": 0,
"URL": "https://uat.webapi.sam.org.au/document/d0a15513-8c60-4695-a9d9-376685df2fc5.jpeg"
},
"default": true
}
]
},
Product Images
There is a cover image/s and then optional image/s per variation. So you will find images in the Variation info as well as at the product level (selected cover image – is denoted as Default).
Comments
0 comments
Article is closed for comments.