Migrating from the SOAP API
When the Orders Harmonization feature is enabled, you can continue to use Subscribe and Amend SOAP APIs to create and manage your subscriptions. If you want to migrate your SOAP integrations to use the Orders REST API, you can still do it.
To assist with the migration, this article provides the SOAP equivalent of the "Create order" request body shown in Renew a Subscription and Upgrade a Product.
SOAP Example
Renewing a subscription and upgrading a product requires three SOAP calls. The first SOAP call renews the subscription. The second SOAP call removes an existing product from the subscription. The third SOAP call adds a replacement product to the subscription.
Renew a Subscription
The following SOAP amend() example is valid for WSDL version 29.0 and later.
<api:amend> <api:requests> <api:Amendments> <obj:ContractEffectiveDate>2017-01-01</obj:ContractEffectiveDate> <obj:CustomerAcceptanceDate>2017-01-01</obj:CustomerAcceptanceDate> <obj:Description>subscripiton renewal</obj:Description> <obj:EffectiveDate>2017-01-01</obj:EffectiveDate> <obj:Name>renewal</obj:Name> <obj:ServiceActivationDate>2017-01-01</obj:ServiceActivationDate> <obj:Status>Completed</obj:Status> <obj:SubscriptionId>8a8081085e0d4b70015e4b8444810589</obj:SubscriptionId> <obj:Type>Renewal</obj:Type> </api:Amendments> <api:AmendOptions> <api:GenerateInvoice>false</api:GenerateInvoice> <api:ProcessPayments>false</api:ProcessPayments> </api:AmendOptions> <api:PreviewOptions> <api:EnablePreviewMode>false</api:EnablePreviewMode> </api:PreviewOptions> </api:requests> </api:amend>
Remove a Product
The following SOAP amend() example is valid for WSDL version 29.0 and later.
<api:amend> <api:requests> <api:Amendments> <obj:ContractEffectiveDate>2017-03-01</obj:ContractEffectiveDate> <obj:CustomerAcceptanceDate>2017-03-01</obj:CustomerAcceptanceDate> <obj:Description>Removing a product</obj:Description> <obj:EffectiveDate>2017-03-01</obj:EffectiveDate> <obj:Name>Removing a product</obj:Name> <obj:RatePlanData> <api:RatePlan> <obj:AmendmentSubscriptionRatePlanId>8a8081085e0d4b70015e4b844495058d </obj:AmendmentSubscriptionRatePlanId> </api:RatePlan> </obj:RatePlanData> <obj:ServiceActivationDate>2017-03-01</obj:ServiceActivationDate> <obj:Status>Completed</obj:Status> <obj:SubscriptionId>8a8081085e0d4b70015e4b8444810589</obj:SubscriptionId> <obj:Type>RemoveProduct</obj:Type> </api:Amendments> <api:AmendOptions> <api:GenerateInvoice>false</api:GenerateInvoice> <api:ProcessPayments>false</api:ProcessPayments> </api:AmendOptions> <api:PreviewOptions> <api:EnablePreviewMode>true</api:EnablePreviewMode> </api:PreviewOptions> </api:requests> </api:amend>
Add a Product
The following SOAP amend() example is valid for WSDL version 29.0 and later.
<ns1:amend> <ns1:requests> <ns1:Amendments> <ns2:ContractEffectiveDate>2017-03-01</ns2:ContractEffectiveDate> <ns2:CustomerAcceptanceDate>2017-03-01</ns2:CustomerAcceptanceDate> <ns2:EffectiveDate>2017-03-01</ns2:EffectiveDate> <ns2:Name>Add a product</ns2:Name> <ns2:RatePlanData> <ns1:RatePlan> <ns2:ProductRatePlanId>8a8081085d834928015d9ce60ef41acf</ns2:ProductRatePlanId> </ns1:RatePlan> <ns1:RatePlanChargeData> <ns1:RatePlanCharge> <ns2:ProductRatePlanChargeId>8a8081085d834928015d9ce6ae821ad1</ns2:ProductRatePlanChargeId> <ns2:Quantity>20</ns2:Quantity> </ns1:RatePlanCharge> </ns1:RatePlanChargeData> </ns2:RatePlanData> <ns2:ServiceActivationDate>2017-03-01</ns2:ServiceActivationDate> <ns2:Status>Completed</ns2:Status> <ns2:SubscriptionId>8a8081085e0d4b70015e4b8444810589</ns2:SubscriptionId> <ns2:Type>NewProduct</ns2:Type> </ns1:Amendments> <ns1:AmendOptions> <ns1:GenerateInvoice>false</ns1:GenerateInvoice> <ns1:ProcessPayments>false</ns1:ProcessPayments> </ns1:AmendOptions> <ns1:PreviewOptions> <ns1:EnablePreviewMode>False</ns1:EnablePreviewMode> </ns1:PreviewOptions> </ns1:requests> </ns1:amend>
Migration Notes
- You only need to make one call using the REST API.
- Specify account numbers instead of account IDs.
- Specify subscription numbers instead of subscription IDs.
- The effective date specified in the SOAP
EffectiveDate
field corresponds to the contract effective date of the order actions in the REST API. - You do not need to specify the status of the amendment in the REST API. Because the amendment will be in the Complete status if the call succeeds. You cannot create draft amendments in Orders.
- To generate invoices and collect payments, specify the
runBilling
andcollectPayment
fields instead of theGenerateInvoice
andProcessPayments
SOAP fields. - Currently, we do not support specifying the name and description of order actions (the corresponding
Name
andDescription
SOAP fields).