Endpoints Reference

openapi 3 0 3 info title sparklayer ignite integration docs contact email support\@sparklayer io mailto\ support\@sparklayer io version 0 0 1 tags name platform connection name customer address name checkout name customer sub accounts paths /v1/{siteenv}/{siteid} post tags \ platform connection summary new platform connection description the sparklayer ignite platform will call this endpoint when the merchant connects sparklayer on the specific platform please note that this endpoint must be idempotent as it may be called multiple times operationid createplatformconnection parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' requestbody content application/json schema type object required \ store id \ spark api client id \ spark api client secret properties store id type string example "1234" description the id of the store on the 3rd party platform spark api client id type string example ca7cf4ac 51cb 4836 9a79 d425afc6e280 spark api client secret type string example puwuwjzrfsnpb7nenulmw67prs94qybu2dxhl3sh responses '201' description successful operation app install pending content application/json schema type object required \ redirect url properties redirect url description platform store app install url to redirect the merchant to in order to complete the connection type string example https //store 1234 example io/install https //store 1234 example io/install '204' description successful operation app already installed platform connection is now active '401' description auth failure '500' description system exception delete tags \ platform connection summary remove platform connection description sparklayer ignite platform will call this endpoint when the merchant disconnects sparklayer on the specific platform operationid removeplatformconnection parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' responses '204' description successful operation '401' description auth failure '500' description system exception /v1/{siteenv}/{siteid}/customers put tags \ customer summary create/update a customer description > create or update a "customer" on the ecommerce platform the email address of the customer should be used as the unique identifier for finding the customer on the target platform if the target platform has the ability to send an activation / invitation email to the new customer then this should be done operationid createupdatecustomer parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' requestbody content application/json schema type object required \ email \ first name \ last name properties email type string example bob\@sparklayer io mailto\ bob\@sparklayer io format email first name type string example bob minlength 3 maxlength 128 last name type string example jones minlength 3 maxlength 128 company name maxlength 128 type string example tom jones climbing ltd nullable true sales agent groups type array items type string example \["group 1"] nullable true price lists type array items type string example \["25 off"] nullable true customer discount percentage type number example 25 nullable true group maxlength 128 type string example 50 off nullable true role type string example limited customer nullable true enum \ main \ limited customer required true responses '201' description successful operation content application/json schema type object properties customer external id description platform id of customer type string example cu1234 '401' description auth failure '500' description system exception /v1/{siteenv}/{siteid}/sub accounts post tags \ customer sub accounts summary create a new customer sub account description > create a new "customer" on the ecommerce platform and designates it as a sub account with parent customer id as an attribute the implementation should explicitly handle the possibility that a customer with the supplied email address already exists and return a 400 response as documented if the target platform has the ability to send an activation / invitation email to the new customer then this should be done operationid createsubaccount parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' requestbody content application/json schema type object required \ email \ first name \ last name \ parent customer external id properties email type string example bob\@sparklayer io mailto\ bob\@sparklayer io format email first name type string example bob minlength 3 maxlength 128 last name type string example jones minlength 3 maxlength 128 parent customer external id description parent customer id of the customer type string example cu1234 role description a role that represents the users permissions type string example limited customer enum \ main \ limited customer required true responses '201' description successful operation content application/json schema type object properties customer external id description platform id of customer type string example cu1234 '400' description error handling request such as email already taken content application/json schema type object properties error code description machine readable error code such as email already taken type string enum \['email already taken'] example "email already taken" '401' description auth failure '500' description system exception /v1/{siteenv}/{siteid}/sub accounts/{customer external id} patch tags \ customer sub accounts summary update an existing customer sub account description > update the details of an existing customer sub account this allows changing the account's first name, last name and role this does not allow for the email to be updated operationid updatesubaccount parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' \ name customer external id in path description platform id of customer required true schema type string minlength 1 requestbody content application/json schema type object properties first name type string example bob minlength 3 maxlength 128 last name type string example jones minlength 3 maxlength 128 role description a role that represents the users permissions type string example limited customer enum \ main \ limited customer required true responses '201' description successful operation '400' description error handling request such as name too short '401' description auth failure '500' description system exception delete tags \ customer sub accounts summary remove a customer sub account description > remove a customer sub account from the specific platform, ensuring the account can no longer interact with the parent account platforms may prevent the deletion of customers which have orders, for this reason it is recommended that the `parent customer external id` attribute is removed from the customer object rather than actual deletion operationid deletesubaccount parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' \ name customer external id in path description platform id of customer required true schema type string minlength 1 responses '204' description successful operation '404' description customer not found '401' description auth failure '500' description system exception /v1/{siteenv}/{siteid}/customers/{customer external id}/addresses post tags \ customer address summary create a new customer address description | create a new "address" for a customer on the specific platform operationid createcustomeraddress parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' \ $ref '#/components/parameters/customerexternalid' requestbody $ref '#/components/requestbodies/address' responses '201' $ref '#/components/responses/address' '401' description auth failure '500' description system exception /v1/{siteenv}/{siteid}/customers/{customer external id}/addresses/{customer address external id} put tags \ customer address summary update a customer address description | update a customer address on the specific platform operationid updatecustomeraddress parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' \ $ref '#/components/parameters/customerexternalid' \ name customer address external id in path description ecommerce platform id of customer address required true schema type string minlength 1 requestbody $ref '#/components/requestbodies/address' responses '200' $ref '#/components/responses/address' '401' description auth failure '500' description system exception delete tags \ customer address summary remove a customer address description | remove a customer address from the specific platform operationid deletecustomeraddress parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' \ name customer external id in path description ecommerce platform id of customer required true schema type string minlength 1 \ name customer address external id in path description ecommerce platform id of customer address required true schema type string minlength 1 responses '204' description successful operation '401' description auth failure '500' description system exception /v1/{siteenv}/{siteid}/checkout/calculate post tags \ checkout summary calculate tax and shipping description | this endpoint is called at the final step of the checkout process in order to show tax and shipping methods available to the customer operationid calculateorder parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' requestbody description checkout required true content application/json schema $ref '#/components/schemas/checkout' responses '200' $ref '#/components/responses/calculate' '401' description auth failure '500' description system exception /v1/{siteenv}/{siteid}/checkout/complete post tags \ checkout summary complete checkout description | this endpoint is called at the final step once the customer attempts to complete the order if the payment type is upfrontpayment the customer should be directed to the checkout flow to complete payment alternatively, an order can be created there and then for other systems to manage payments at this point, either redirect the user to a url to complete the transaction or return a id of the order being created on the platform operationid completeorder parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' requestbody description checkout required true content application/json schema allof \ $ref '#/components/schemas/checkout' \ type object properties payment type type string enum \[upfrontpayment, paymentonaccount, paymentbyinvoice, quote] sales agent nullable true allof \ $ref '#/components/schemas/salesagent' company user nullable true allof \ $ref '#/components/schemas/customer' additional info type string nullable true description an optional note to be added to the order custom fields type object nullable true description custom fields to be added to the order these are customer defined and dynamic additionalproperties true discount data $ref '#/components/schemas/discountdata' discount coupon codes nullable true type array description a list of all the coupon codes applied to the order items type string minlength 1 responses '201' $ref '#/components/responses/complete' '401' description auth failure '500' description system exception /v1/{siteenv}/{siteid}/status/{syncdatatype} post tags \ data sync summary trigger a data sync description | allow internal users (e g support staff) to trigger a manual sync external to the standard process operationid triggerdatasync parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' \ $ref '#/components/parameters/syncdatatype' responses '201' description initiated data sync '400' description unable to trigger another data sync as there is one in progress '401' description auth failure '500' description system exception \# get /v1/{siteenv}/{siteid}/authentication/verify post tags \ authentication summary verify authentication data provided by the platform description | verifies authentication data, such as a jwt, provided by the platform on the front end operationid authenticationverify parameters \ $ref '#/components/parameters/siteenv' \ $ref '#/components/parameters/siteid' requestbody description > data to verify it must be possible to derive the platform external id for the customer from this data in order to satisfy the response criteria required true content 'application/json' schema type object required \ data properties data type string responses '200' description data is verified content application/json schema type object properties customer type object required \ external id properties external id description ecommerce platform id of customer type string example cu1234 '400' $ref '#/components/responses/default' components parameters siteid name siteid in path required true schema type string example bobs store minlength 1 siteenv name siteenv in path required true schema type string example live syncdatatype name syncdatatype in path required true schema type string enum \[ customers, products ] example products description > either products or customers customerexternalid name customer external id in path description platform id of customer required true schema type string minlength 1 requestbodies address description address content application/json schema $ref '#/components/schemas/address' responses default description error response content application/problem+json schema $ref '#/components/schemas/error' address description successful address content application/json schema $ref '#/components/schemas/addresswithid' calculate description returns tax and shipping information content application/json schema type object properties available shipping methods type array items type object properties id type string example next day name type string example next day delivery price description net of tax type number example 4 80 platform shipping line description | when using ecommerce platform shipping, return the currently set shipping method data this is needed in the case where the ecommerce platform or the ignite integration rejects the suplied shipping method and automatically selects another available shipping method nullable true $ref '#/components/schemas/shippinglineplatform' totals type object properties line items description sub total of line items (nett of tax) type number example 14 80 shipping price description shipping cost (nett of tax) type number example 4 80 tax description tax for the order type number example 2 20 total price description order total (gross of tax) type number example 21 80 ignite state type object description > context which will be provided in subsequent requests to /checkout/complete complete description checkout complete success content application/json schema allof \ type object properties line items type array items type object required \ spark item key \ tax lines properties spark item key type string tax lines type array items type object properties rate type number example 0 2 description tax rate price type number example 1 0 description tax amount platform shipping line description | when using ecommerce platform shipping, return the currently set shipping method data this is needed in the case where the ecommerce platform or the ignite integration rejects the supplied shipping method and automatically selects another available shipping method nullable true $ref '#/components/schemas/shippinglineplatform' \ oneof \ type object properties checkout url description url to send the customer to complete payment, leave null if not required type string nullable true format url example https //checkout bobs store com/checkout/1234/payment https //checkout bobs store com/checkout/1234/payment \ type object properties order id description the platform's unique order id type string example "5342456" schemas shippinglinesparklayer type object description shipping line provided from sparklayer properties type type string enum \[ sparklayer ] id type string name type string price description net of tax type number example 4 80 shippinglineplatform type object description shipping line provided from platform properties type type string enum \[ platform ] id type string name type string price description net of tax type number example 4 80 shippinglineplatformidonly type object description shipping line provided from platform id only properties type type string enum \[ platform ] id type string error title error message response description "structure for returning rfc 7807 errors from api" type object properties detail description human readable detail of the error type string example data validation failed status description http status code returned from api type integer example 400 title description human readable summary of the error type string example "invalid api request contents" type type string example "invalid api request contents" errors description a list of errors related to the call type array nullable true items type object properties code type string description machine readable error code example resource not found property type string description the property the error relates to example stock location id message type string description human readable summary of the error example "stock location id not found" address type object properties title maxlength 30 type string example mr nullable true first name maxlength 50 type string example bob nullable true last name maxlength 50 type string example jones nullable true company maxlength 128 type string example tom jones climbing ltd nullable true address line1 maxlength 255 type string example example industrial estate nullable false address line2 maxlength 255 type string example north country nullable true city maxlength 128 type string example cityland nullable false region name maxlength 128 type string example california nullable true region code maxlength 10 nullable true type string example ca postal code maxlength 20 type string example "12345" nullable true country code description two letter country code as defined by iso 3166 2 maxlength 2 type string example us nullable false phone maxlength 20 type string example +44 (0) 123456789 is default shipping type boolean nullable false is default billing type boolean nullable false addresswithid type object properties title maxlength 30 type string example mr nullable true first name maxlength 50 type string example bob nullable true last name maxlength 50 type string example jones nullable true company maxlength 128 type string example tom jones climbing ltd nullable true address line1 maxlength 255 type string example example industrial estate nullable false address line2 maxlength 255 type string example north country nullable true city maxlength 128 type string example cityland nullable false region name maxlength 128 type string example california nullable true region code maxlength 10 nullable true type string example ca postal code maxlength 20 type string example "12345" nullable true country code description two letter country code as defined by iso 3166 2 maxlength 2 type string example us nullable false phone maxlength 20 type string example +44 (0) 123456789 is default shipping type boolean nullable false is default billing type boolean nullable false customer address external id description ecommerce platform id for the customer address maxlength 50 type string shop type object properties base currency code description " iso 4217 https //en wikipedia org/wiki/iso 4217 currency code" minlength 3 maxlength 3 type string example gbp checkout type object properties cart id description sparklayer cart id type string format uuid example f81d4fae 7dec 11d0 a765 00a0c91e6bf6 nullable false customer allof \ $ref '#/components/schemas/customer' \ type object properties default billing address id description ecommerce platform id of default billing address type string nullable true default shipping address id description ecommerce platform id of default shipping address type string nullable true temporary external address ids description | list of temporary (drop shipping) address ids associated with the customer to be deleted once the order has been completed should be the external (platform) address id type array items type string payment on account type object nullable true properties credit limit type number nullable true format float balance type number nullable true format float net terms type string nullable true enum \ '7 days' \ '15 days' \ '30 days' \ '45 days' \ '60 days' \ '90 days' currency code description " iso 4217 https //en wikipedia org/wiki/iso 4217 currency code" minlength 3 maxlength 3 type string example gbp billing address $ref '#/components/schemas/address' shipping address $ref '#/components/schemas/address' shipping line description | if using platform shipping, on the first load of the final checkout screen, this will be null , after it will be an id from a method from the response of available shipping methods if using sparklayer shipping, this can be null if none found or will be the method nullable true discriminator propertyname type mapping sparklayer '#/components/schemas/shippinglinesparklayer' platform '#/components/schemas/shippinglineplatformidonly' anyof \ $ref '#/components/schemas/shippinglinesparklayer' \ $ref '#/components/schemas/shippinglineplatformidonly' shop $ref '#/components/schemas/shop' line items type array nullable false items type object properties spark item key type string maxlength 32 example 00a0c91e6bf600a0c91e6bf spark variant id type string maxlength 32 example pv 134 sku type string example example sku product variant external id description ecommerce platform id of product variant type string example prod123456 product external id description ecommerce platform id of product type string example prod1234 quantity type integer example 10 unit price description net price of a unit type number example 4 80 custom attributes description custom attributes allow arbitrary data to be attached to a line item type array items type object properties key type string value type string options type array nullable true items type object properties group type string value type string ignite state type object description > context which was set by a previous response from /checkout/calculate customer type object required \ id \ external id \ email properties id description sparklayer id of customer type string example cu 1 email type string format email external id description ecommerce platform id of customer type string example cus1234 accounting id type string nullable true salesagent type object required \ id \ email properties id description sparklayer id of sales agent type string example cu 1 email type string format email accounting id type string nullable true discountdata type object nullable true properties sub total pre discount $ref '#/components/schemas/currencytotal' sub total discount $ref '#/components/schemas/currencytotal' line item discounts type array items $ref '#/components/schemas/lineitemdiscount' discount slugs type array items type string required \ sub total pre discount \ sub total discount \ line item discounts \ discount slugs currencytotal type object properties net type number format float required \ net lineitemdiscount type object properties pre discount $ref '#/components/schemas/currencytotal' discount $ref '#/components/schemas/currencytotal' sku type string item key type string required \ pre discount \ discount \ sku \ item key