Overview
The purpose of this API call is to initiate a new Order.
SOAP Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:emersion:api" xmlns:urn1="urn:emersion:types">
<soapenv:Header/>
<soapenv:Body>
<urn:StartOrderRequest>
<urn:AccountID>3898888</urn:AccountID>
<!--Optional:-->
<urn:CumulusUserID>1029690</urn:CumulusUserID>
<!--Optional:-->
<urn:PurchaseOrder>PO443454</urn:PurchaseOrder>
<!--Optional:-->
<urn:PromoCode>?</urn:PromoCode>
<!--Optional:-->
<urn:ExternalContractIdentifier>4445344</urn:ExternalContractIdentifier>
<!--Optional:-->
<urn:Commissions>
<!--Zero or more repetitions:-->
<urn1:Commission>
<urn1:CommissionLedgerCardlineID>1111223</urn1:CommissionLedgerCardlineID>
<urn1:CommissionObjectLogID>2468901</urn1:CommissionObjectLogID>
<!--Optional:-->
<urn1:InvoiceID>1886255</urn1:InvoiceID>
<urn1:CommissionObjectType>ProductSales</urn1:CommissionObjectType>
<urn1:CommissionAccountID>4004852</urn1:CommissionAccountID>
<urn1:CommissionOrgUnitID>1002183</urn1:CommissionOrgUnitID>
<urn1:AgentCode>AGENT007</urn1:AgentCode>
<urn1:CommissionPlanName>Standard Plan</urn1:CommissionPlanName>
<urn1:SourceLedgerCardlineID>8234981</urn1:SourceLedgerCardlineID>
<urn1:SourceLedgerCardlineDescription>Service Charge</urn1:SourceLedgerCardlineDescription>
<urn1:SourceAccountID>7007159</urn1:SourceAccountID>
<!--Optional:-->
<urn1:SourceServiceID>8008357</urn1:SourceServiceID>
<!--Optional:-->
<urn1:SourceServiceIdentifier>Service01234</urn1:SourceServiceIdentifier>
<urn1:CustomerVisible>true</urn1:CustomerVisible>
<urn1:CommissionAmount>350.75</urn1:CommissionAmount>
<urn1:CommissionTax>15.07</urn1:CommissionTax>
<urn1:IsUsage>false</urn1:IsUsage>
<!--Optional:-->
<urn1:ApprovedDate>2024-06-19T00:00:00+00:00</urn1:ApprovedDate>
<!--Optional:-->
<urn1:ApprovedUser>admin</urn1:ApprovedUser>
</urn1:Commission>
</urn:Commissions>
</urn:StartOrderRequest>
</soapenv:Body>
</soapenv:Envelope>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:emersion:api">
<soapenv:Header/>
<soapenv:Body>
<urn:StartOrderResponse>
<urn:AccountPresaleID>567890</urn:AccountPresaleID>
<urn:Status>true</urn:Status>
</urn:StartOrderResponse>
</soapenv:Body>
</soapenv:Envelope>
Field Descriptions
All field names are case sensitive. Check enumerated values in the descriptions to confirm capitalisation and spacing. See field types for additional information.
| Name | Description | Required? | Field Type | Character limit | Values |
|---|---|---|---|---|---|
AccountId | Account ID that you wish to perform an order against. | Yes | Integer | Must be greater than six digits | 3898888 |
| CumulusUserID | Cumulus User creating the order. | No | Integer | 1029690 | |
PurchaseOrder | Custom Field representing a purchase Order. | No | String | 50 characters | PO443454 |
PromoCode | Custom Field for discounts or offers. | No | String | 255 characters | PROMO2024 |
ExternalContractIdentifier | Custom Field representing a contract ID or Reference. | No | String | 50 characters | 4445344 |
Commissions | A collection of Commission details that may include multiple commission elements. | No | Commissions |
The Commissions field can have several commission elements, each having the following fields:
| Name | Description | Required? | Field Type | Character limit | Values |
|---|---|---|---|---|---|
CommissionLedgerCardlineID | Unique identifier for the commission ledger card line. | Yes | Integer | 1111223 | |
CommissionObjectLogID | Unique identifier for the commission object log. | Yes | Integer | 2468901 | |
InvoiceID | Unique identifier for the invoice. | No | Integer | 1886255 | |
CommissionObjectType | Type of the commission object. | Yes | String | ProductSales | |
CommissionAccountID | Unique identifier for the commission account. | Yes | Integer | 4004852 | |
CommissionOrgUnitID | Unique identifier for the commission organizational unit. | Yes | Integer | 1002183 | |
AgentCode | Code assigned to the agent handling the commission. | Yes | String | AGENT007 | |
CommissionPlanName | Name of the commission plan. | Yes | String | Standard Plan | |
SourceLedgerCardlineID | Unique identifier for the source ledger card line. | Yes | Integer | 8234981 | |
SourceLedgerCardlineDescription | Description of the source ledger card line. | Yes | String | Service Charge | |
SourceAccountID | Unique identifier for the source account. | Yes | Integer | 7007159 | |
SourceServiceID | Unique identifier for the source service. | No | Integer | 8008357 | |
SourceServiceIdentifier | Identifier for the source service. | No | String | Service01234 | |
CustomerVisible | Indicates whether the commission is visible to the customer. | Yes | Boolean | true | |
CommissionAmount | The amount of the commission. | Yes | double | 350.75 | |
CommissionTax | Tax applied to the commission amount. | Yes | double | 15.07 | |
IsUsage | Indicates if the commission is based on usage. | Yes | Boolean | false | |
ApprovedDate | The date when the commission was approved. | No | DateTime | 2024-06-19T00:00:00+00:00 | |
ApprovedUser | The user who approved the commission. | No | String | admin |
Error Handling
| Error Message | Description |
|---|---|
| Account Type is not eligible to create order | The account is an account of type Wholesale. You cannot place orders against wholesale accounts. |
| Order creation is restricted for this account | The account is in a status that does not permit ordering (cancelled, inactive). |
| The account is suspended - please contact your upstream provider. | The account status is in suspended or restricted status. |
| Missing Account ID | You have not provided an account ID. |
| Invalid Account ID | The ID you have provided is less than six digits in length. |
| Undefined Account | The account you specified doesn't exist, or you don't have access to perform an API call to this account. |
| Purchase Order length exceed limit | String exceeds field limit of 50 characters. |
| External contract identifier length exceed limit | String exceeds field limit of 50 characters. |
| Undefined Cumulus User | The cumulus user must be a staff member owned by the calling account. |