SilverCart › Techbase › Develop › Restful API

Restful API

SilverCart offers a restful api service that can be used to request data about orders, customers, payment methods etc.

Security

By default, only users with administrator privileges are allowed to call the service.

Unlike the default Silverstripe API a requester doesn't need to be logged in to perform requests. If one's not logged in already, an HTTP Basic Authentification will be used to gain access.

Some SilverCart classes provide special access restrictions (e.g. SilvercartOrder) that have to be taken into account.

How to start a request

The service is reachable under "http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/".

There's a common pattern to invoke requests with SilvercartRestfulServer.

  • GET /api/silvercart/(ClassName) - gets all database records of the given class name
  • GET /api/silvercart/(ClassName)/(ID) - gets a database record
  • GET /api/silvercart/(ClassName)/(ID)/(Relation) - get all of the records linked to this database record by the given relation
  • GET /api/silvercart/(ClassName)?(Field)=(Val)&(Field)=(Val) - searches for matching database records

Request modifiers

Every request can be modified with URL parameters. At this moment you can use the following ones:

  • &start=<numeric> Start at a position in the result set
  • &limit=<numeric> Limit the result set
  • &sort={FIELD_NAME}&dir={asc|desc} sort the result set ascending or descending
  • &add_fields=<string> Comma-separated list of fields to export. This list replaces the default fields.

Supported request classes

Currently the following SilverCart classes support API access:

  • Member
  • Group
  • SilvercartOrder
  • SilvercartOrderPosition
  • SilvercartOrderStatus
  • SilvercartPaymentMethod
  • SilvercartShippingMethod

Request structure and examples

Request orders

Orders can be requested by invoking the URL

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder

Search orders by date and date ranges

Searches by the order date should be applied to the "Created" field. There's one caveout though: dates need to be in german format (dd.mm.yyyy).

Examples:

Get all orders from may 6th, 2013:

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder?Created=06.03.2013

Get all orders from may 6th, 2013 to may 14th, 2013:

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder?Created=06.03.2013-14.03.2013

Search orders by order status

Searches by order status should be applied to the "SilvercartOrderStatus__ID" field. It's possible to search for more than one order status, so the field needs to be an array ("SilvercartOrderStatus__ID[]").

Every order status can be set to influence the result positively or negatively ("SilvercartOrderStatus__ID[]=1 or "SilvercartOrderStatus__ID[]=0").

Examples:

Get all orders with a given order status

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder?SilvercartOrderStatus__ID[{ORDER\_STATUS_ID}]=1

Get all orders by multiple given order status

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder?SilvercartOrderStatus__ID[{ORDER_STATUS_ID_1}]=1&SilvercartOrderStatus__ID[{ORDER_STATUS_ID_2}]=1

Get all orders that don't have a given order status

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder?SilvercartOrderStatus__ID[{ORDER_STATUS_ID}]=0

Get all orders that don't have any of the given order status

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder?SilvercartOrderStatus__ID[{ORDER_STATUS_ID_1}]=0&SilvercartOrderStatus__ID[{ORDER_STATUS_ID_2}]=0

Request a single order

URL: http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder/{ORDER_ID}

Request all positions for an order

URL: http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrder/{ORDER_ID}/SilvercartOrderPositions

Request order status

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartOrderStatus

Request payment methods

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartPaymentMethod

Request shipping methods

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/SilvercartShippingMethod

Request members

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/Member

Request all orders for a member

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/Member/{MEMBER_ID}/SilvercartOrder

Request groups

http://{URL_TO_YOUR_WEBSHOP}/api/silvercart/Group

Response structure and examples

The API responses are always embedded into the root element "DataObjectSet" which has an attribute "totalSize" containing the number of found records.

<DataObjectSet totalSize="3">
    ...
</DataObjectSet>

Response for an order list

<DataObjectSet totalSize="{number of total records found, e.g. 1560}">
    <SilvercartOrder href="{SHOP_URL}/api/silvercart/SilvercartOrder/32889.xml">
        <AmountTotal>{e.g. 67.34}</AmountTotal>
        <PriceType>{can be "gross" or "net"}</PriceType>
        <HandlingCostPayment>{e.g. 0}</HandlingCostPayment>
        <HandlingCostShipment>{e.g. 3.76}</HandlingCostShipment>
        <TaxRatePayment>{e.g. 0}</TaxRatePayment>
        <TaxRateShipment>{e.g. 19}</TaxRateShipment>
        <TaxAmountPayment>0</TaxAmountPayment>
        <TaxAmountShipment>0.600336</TaxAmountShipment>
        <Note>{The customer's notes}</Note>
        <WeightTotal>0</WeightTotal>
        <CustomersEmail>{EmailAdress}}</CustomersEmail>
        <OrderNumber>200830</OrderNumber>
        <AmountGrossTotal/>
        <DirectDebitBankAccountHolder/>
        <DirectDebitBankCode/>
        <DirectDebitBankAccountNumber/>
        <DirectDebitBankName/>
        <DirectDebitBankIban/>
        <DirectDebitBankBic/>
        <ID>{ID}</ID>

        <SilvercartOrderShippingAddress href="{SHOP_URL}/api/silvercart/SilvercartOrderShippingAddress/88405.xml">
            <TaxIdNumber>{TaxIdNumber}</TaxIdNumber>
            <Company>{CompanyName}</Company>
            <Salutation>{Salutation}</Salutation>
            <FirstName>{FirstName}</FirstName>
            <Surname>{Surname}</Surname>
            <Addition>{Address addition}</Addition>
            <PostNumber/>
            <Packstation/>
            <Street>{StreetName}</Street>
            <StreetNumber>{StreetNumber}</StreetNumber>
            <Postcode>{PostCode}</Postcode>
            <City>{City}</City>
            <PhoneAreaCode>{PhoneAreaCode}</PhoneAreaCode>
            <Phone>{Phone}</Phone>
            <Fax>{Fax}}</Fax>
            <IsPackstation>{0 or 1 if address is a Packstation address}</IsPackstation>
            <SilvercartCountryISO2>DE</SilvercartCountryISO2>
            <SilvercartCountryISO3>DEU</SilvercartCountryISO3>
            <SilvercartCountryISON>276</SilvercartCountryISON>
            <SilvercartCountryFIPS>GM</SilvercartCountryFIPS>
            <ID>88405</ID>
        </SilvercartOrderShippingAddress>

        <SilvercartOrderInvoiceAddress href="{SHOP_URL}/api/silvercart/SilvercartOrderInvoiceAddress/88406.xml">
            <TaxIdNumber>{TaxIdNumber}</TaxIdNumber>
            <Company>{CompanyName}</Company>
            <Salutation>{Salutation}</Salutation>
            <FirstName>{FirstName}</FirstName>
            <Surname>{Surname}</Surname>
            <Addition>{Address addition}</Addition>
            <PostNumber/>
            <Packstation/>
            <Street>{StreetName}</Street>
            <StreetNumber>{StreetNumber}</StreetNumber>
            <Postcode>{PostCode}</Postcode>
            <City>{City}</City>
            <PhoneAreaCode>{PhoneAreaCode}</PhoneAreaCode>
            <Phone>{Phone}</Phone>
            <Fax>{Fax}}</Fax>
            <IsPackstation>{0 or 1 if address is a Packstation address}</IsPackstation>
            <SilvercartCountryISO2>DE</SilvercartCountryISO2>
            <SilvercartCountryISO3>DEU</SilvercartCountryISO3>
            <SilvercartCountryISON>276</SilvercartCountryISON>
            <SilvercartCountryFIPS>GM</SilvercartCountryFIPS>
            <ID>{ID}</ID>
        </SilvercartOrderInvoiceAddress>

        <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentPrepayment/4.xml">
            <PaymentChannel>prepayment</PaymentChannel>
            <ID>4</ID>
        </SilvercartPaymentMethod>

        <SilvercartShippingMethod href="{SHOP_URL}/api/silvercart/SilvercartShippingMethod/5.xml">
            <ID>5</ID>
        </SilvercartShippingMethod>

        <SilvercartOrderStatus href="{SHOP_URL}/api/silvercart/SilvercartOrderStatus/3.xml">
            <Code>pending</Code>
            <ID>3</ID>
        </SilvercartOrderStatus>

        <Member href="{SHOP_URL}/api/silvercart/Member/2.xml">
            <FirstName>{FirstName}</FirstName>
            <Surname>{Surname}</Surname>
            <Email>{Email}</Email>
            <Salutation>{Salutation, can be "Herr" or "Frau"}</Salutation>
            <NewsletterOptInStatus>{0 or 1, NewsletterOptInStatus}</NewsletterOptInStatus>
            <SubscribedToNewsletter>{0 or 1, SubscribedToNewsletter}</SubscribedToNewsletter>
            <Birthday/>
            <CustomerNumber>{CustomerNumber}</CustomerNumber>
            <ID>{ID}</ID>
        </Member>

        <SilvercartOrderPositions linktype="has_many" href="{SHOP_URL}/api/silvercart/SilvercartOrder/32889/SilvercartOrderPositions.xml">
            <SilvercartOrderPosition href="{SHOP_URL}/api/silvercart/SilvercartOrderPosition/65630.xml">
                <Price>{Price, e.g. 64.95)}</Price>
                <PriceTotal>{Price total, e.g. 64.95}</PriceTotal>
                <isChargeOrDiscount>{0 or 1, indicates if this position is a charge or discount}</isChargeOrDiscount>
                <isIncludedInTotal>{0 or 1, indicates if this position is already included in the total price}</isIncludedInTotal>
                <chargeOrDiscountModificationImpact>{"none", "productValue" or "totalValue"}</chargeOrDiscountModificationImpact>
                <Tax>{Tax, e.g. 10.3702}</Tax>
                <TaxTotal>{Tax total, e.g. 10.3702}</TaxTotal>
                <TaxRate>{Tax rate, e.g. 19}</TaxRate>
                <ProductDescription/>
                <Quantity>{Quantity, e.g. 1.00}</Quantity>
                <Title>{Title}</Title>
                <ProductNumber>{Product number, e.g. 7d56405W}</ProductNumber>
                <SilvercartVoucherCode/>
                <SilvercartVoucherValue/>
                <ID>{ID}</ID>
            </SilvercartOrderPosition>

            <SilvercartOrderPosition href="{SHOP_URL}/api/silvercart/SilvercartOrderPosition/65631.xml">
                ...
            </SilvercartOrderPosition>
        </SilvercartOrderPositions>
    </SilvercartOrder>
</DataObjectSet>

Response for an order position

<DataObjectSet totalSize="1">
    <SilvercartOrderPosition href="{SHOP_URL}/api/silvercart/SilvercartOrderPosition/65630.xml">
        <Price>{Price, e.g. 64.95)}</Price>
        <PriceTotal>{Price total, e.g. 64.95}</PriceTotal>
        <isChargeOrDiscount>{0 or 1, indicates if this position is a charge or discount}</isChargeOrDiscount>
        <isIncludedInTotal>{0 or 1, indicates if this position is already included in the total price}</isIncludedInTotal>
        <chargeOrDiscountModificationImpact>{"none", "productValue" or "totalValue"}</chargeOrDiscountModificationImpact>
        <Tax>{Tax, e.g. 10.3702}</Tax>
        <TaxTotal>{Tax total, e.g. 10.3702}</TaxTotal>
        <TaxRate>{Tax rate, e.g. 19}</TaxRate>
        <ProductDescription/>
        <Quantity>{Quantity, e.g. 1.00}</Quantity>
        <Title>{Title}</Title>
        <ProductNumber>{Product number, e.g. 7d56405W}</ProductNumber>
        <SilvercartVoucherCode/>
        <SilvercartVoucherValue/>
        <ID>{ID}</ID>
    </SilvercartOrderPosition>
</DataObjectSet>

Response for an order status list

<DataObjectSet totalSize="2">
    <SilvercartOrderStatus href="{SHOP_URL}/api/silvercart/SilvercartOrderStatus/21.xml">
        <Code>finished</Code>
        <ID>21</ID>
    </SilvercartOrderStatus>
    <SilvercartOrderStatus href="{SHOP_URL}/api/silvercart/SilvercartOrderStatus/3.xml">
        <Code>pending</Code>
        <ID>3</ID>
    </SilvercartOrderStatus>
</DataObjectSet>

Response for a payment method list

<DataObjectSet totalSize="8">
    <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentIPayment/1.xml">
        <PaymentChannel>cc</PaymentChannel>
        <Name>Kreditkarte / Debitkarte (iPayment)</Name>
        <ID>1</ID>
    </SilvercartPaymentMethod>
    <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentIPayment/2.xml">
        <PaymentChannel>elv</PaymentChannel>
        <Name>Lastschrift (iPayment)</Name>
        <ID>2</ID>
    </SilvercartPaymentMethod>
    <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentPaypal/3.xml">
        <Name>Paypal</Name>
        <ID>3</ID>
    </SilvercartPaymentMethod>
    <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentPrepayment/4.xml">
        <PaymentChannel>prepayment</PaymentChannel>
        <Name>Vorkasse</Name>
        <ID>4</ID>
    </SilvercartPaymentMethod>
    <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentPrepayment/5.xml">
        <PaymentChannel>invoice</PaymentChannel>
        <Name>Rechnung</Name>
        <ID>5</ID>
    </SilvercartPaymentMethod>
    <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentSaferpay/6.xml">
        <Name>Kreditkarte</Name>
        <ID>6</ID>
    </SilvercartPaymentMethod>
    <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentCOD/7.xml">
        <Name>Nachnahme</Name>
        <ID>7</ID>
    </SilvercartPaymentMethod>
    <SilvercartPaymentMethod href="{SHOP_URL}/api/silvercart/SilvercartPaymentDirectDebit/8.xml">
        <Name>Lastschrift</Name>
        <ID>8</ID>
    </SilvercartPaymentMethod>
</DataObjectSet>

Response for a shipping method list

<DataObjectSet totalSize="3">
    <SilvercartShippingMethod href="{SHOP_URL}/api/silvercart/SilvercartShippingMethod/4.xml">
        <Title>DHL Paket</Title>
        <ID>4</ID>
    </SilvercartShippingMethod>
    <SilvercartShippingMethod href="{SHOP_URL}/api/silvercart/SilvercartShippingMethod/5.xml">
        <Title>Hermes Versand</Title>
        <ID>5</ID>
    </SilvercartShippingMethod>
    <SilvercartShippingMethod href="{SHOP_URL}/api/silvercart/SilvercartShippingMethod/6.xml">
        <Title>Briefpost</Title>
        <ID>6</ID>
    </SilvercartShippingMethod>
</DataObjectSet>

Response for a member list

<DataObjectSet totalSize="22022">
    <Member href="{SHOP_URL}/api/silvercart/Member/4.xml">
        <FirstName/>
        <Surname/>
        <Email/>
        <Salutation/>
        <NewsletterOptInStatus/>
        <SubscribedToNewsletter/>
        <Birthday/>
        <CustomerNumber/>
        <ID/>
    </Member>
</DataObjectSet>

Response for a group list

<DataObjectSet totalSize="5">
    <Group href="URL_TO_YOUR_WEBSHOP/api/silvercart/Group/1.xml">
        <Title>Inhaltsautoren</Title>
        <Description/>
        <Code>content-authors</Code>
        <Pricetype>---</Pricetype>
        <ID>1</ID>
    </Group>
    <Group href="URL_TO_YOUR_WEBSHOP/api/silvercart/Group/2.xml">
        <Title>Administratoren</Title>
        <Description/>
        <Code>administrators</Code>
        <Pricetype>---</Pricetype>
        <ID>2</ID>
    </Group>
    <Group href="URL_TO_YOUR_WEBSHOP/api/silvercart/Group/3.xml">
        <Title>Anonymer Kunde</Title>
        <Description/>
        <Code>anonymous</Code>
        <Pricetype>gross</Pricetype>
        <ID>3</ID>
    </Group>
    <Group href="URL_TO_YOUR_WEBSHOP/api/silvercart/Group/4.xml">
        <Title>Händler</Title>
        <Description/>
        <Code>b2b</Code>
        <Pricetype>gross</Pricetype>
        <ID>4</ID>
    </Group>
    <Group href="URL_TO_YOUR_WEBSHOP/api/silvercart/Group/5.xml">
        <Title>Endkunde</Title>
        <Description/>
        <Code>b2c</Code>
        <Pricetype>gross</Pricetype>
        <ID>5</ID>
    </Group>
</DataObjectSet>