To add a complimentary subscription to a subscriber, do an HTTP POST like so:
[ ~ ] $ curl -u 2dac9d3d93326f97da4845d407789da232514b48:X -H 'Content-Type: application/xml' -d '<complimentary-subscription><duration-quantity>2</duration-quantity><duration-units>months</duration-units><feature-level>Pro</feature-level></complimentary-subscription>' https://spreedly.com/api/v4/meresheep/subscribers/444/complimentary_subscriptions.xml
Here is the response:
<?xml version="1.0" encoding="UTF-8"?>
<subscriber>
<active type="boolean">true</active>
<active-until type="datetime">2008-02-21T19:04:28Z</active-until>
<billing-first-name></billing-first-name>
<billing-last-name></billing-last-name>
<card-expires-before-next-auto-renew type="boolean">false</card-expires-before-next-auto-renew>
<created-at type="datetime">2007-12-21T18:54:24Z</created-at>
<customer-id>444</customer-id>
<eligible-for-free-trial type="boolean">false</eligible-for-free-trial>
<email></email>
<feature-level type="string">Pro</feature-level>
<lifetime-subscription type="boolean">false</lifetime-subscription>
<on-trial type="boolean">false</on-trial>
<recurring type="boolean">false</recurring>
<screen-name>freddy</screen-name>
<store-credit type="decimal">0.0</store-credit>
<subscription-plan-name>Super Pro Account</subscription-plan-name>
<token>1c08af7ef78f1a4b51127cf0ddfe7b2b24681b6c</token>
<updated-at type="datetime">2007-12-21T19:04:28Z</updated-at>
</subscriber>
If successful, a status code of 201 (Created) is returned. The xml of the subscriber is returned in the response body. In addition, the Location header in the response will be set to the url of the subscriber.
A 404 (Not Found) status code is returned if there is no subscriber with the customer id. A 422 (Unprocessable Entity) is returned if there are any validation errors on the passed in Complimentary Subscription.
A 403 (Forbidden) status code is returned if the subscriber is active. Complimentary subscriptions can only be added to inactive subscribers.
If you'd like a complimentary subscription added via the API to carry a value so that it will be pro-rated when upgraded, you can specify a start time and amount:
[ ~ ] $ curl -u 2dac9d3d93326f97da4845d407789da232514b48:X -H 'Content-Type: application/xml' -d '<complimentary-subscription>
<start-time>2007-12-01T00:00:00Z</start-time>
<amount>50</amount>
<duration-quantity>2</duration-quantity>
<duration-units>months</duration-units>
<feature-level>Pro</feature-level>
</complimentary-subscription>' https://spreedly.com/api/v4/meresheep/subscribers/444/complimentary_subscriptions.xml
If a subscriber with this comp subscribed to a paid plan on 2008-01-01, they would get a credit of $25 against their new subscription price since half of the comp is left.