Core Resources

Onetimes

Onetimes represent non-recurring line items on a QUEUED Charge.

39 additions in V2, marked New

Everything marked New also works when you send X-Recharge-Version: 2021-11.

Endpoints

POST/onetimes
GET/onetimes/{id}
PUT/onetimes/{id}
DELETE/onetimes/{id}
GET/onetimes

#The onetime object

Attributes

idinteger
Unique numeric identifier for the Onetime purchase.
address_idinteger
Unique numeric identifier for the address the Onetime Purchase is associated with (cannot be used with next_charge_scheduled_at)
includeobjectNew
An object containing the related objects requested with the include query parameter.
Only returned when the include query parameter is passed on the retrieve or list endpoints.
Show child attributesHide child attributes712 new
- addressobjectNew
  The Address the Onetime is associated with.
  Returned when include contains address.
- bundle_productobject · nullableNew
  The bundle product that matches the product of the Onetime. null if the product is not a bundle.
  Returned when include contains bundle_product.
- bundle_selectionsobject · nullableNew
  The BundleSelection linked to the Onetime. null if there is none.
  Returned when include contains bundle_selections.
- charge_activitiesarrayNew
  The charge activity records created in the last 90 days for the Charges that contain the Onetime.
  Returned when include contains charge_activities.
- customerobjectNew
  The Customer the Onetime is tied to.
  Returned when include contains customer.
- customer_entitlementsarray of objectsNew
  The entitlements granted to the Customer by the Onetime.
  Returned when include contains customer_entitlements.
  Show child attributesHide child attributes55 new
  - idintegerNew
    Unique numeric identifier for the customer entitlement.
  - descriptionstring · nullableNew
    The description of the entitlement feature.
  - expires_atdatetime · nullableNew
    The time the entitlement expires. null if it does not expire.
  - lookup_keystringNew
    The lookup key of the entitlement feature.
  - namestringNew
    The name of the entitlement feature.
- metafieldsarrayNew
  The Metafields attached to the Onetime.
  Returned when include contains metafields.
presentment_currencystring · nullableNew
The presentment currency of the Onetime.
created_atdatetime
The time the Onetime item was first created.
customer_idinteger
Unique numeric identifier for the customer the Onetime purchase is tied to.
external_product_idobject
An object containing the product id as it appears in external platforms.
Show child attributesHide child attributes1
- ecommercestring
  The product id as it appears in the external e-commerce platform. The external_product_id of the Product record in Recharge, linking a Plan to a Product.
external_variant_idobject
An object containing the variant id as it appears in external platforms.
Show child attributesHide child attributes1
- ecommercestring
  The variant id as it appears in the external e-commerce platform. The external_variant_id of the Product record in Recharge, linking a Plan to a Product.
is_cancelledboolean
Flag indicating if the the onetime is cancelled.
next_charge_scheduled_atdate
Date of the Onetime purchase execution.
Cannot be used with add_to_next_charge
pricestring
The price of the item before discounts, taxes, or shipping have been applied.
product_titlestring
The name of the product in a shop’s catalog.
propertiesarray of objects
An array containing key value pairs for any supplementary data.
Show child attributesHide child attributes2
- namestring
  The name of the property.
- valuestring
  The value of the property.
quantityinteger
The number of items in the Onetime purchase.
skustring
A unique identifier of the item in the fulfillment.
sku_overrideboolean
Flag that is automatically updated to true when SKU is passed on POST or PUT.
When sku_override is true, the sku on the Onetime will be used to generate Charges and Orders.
When sku_override is false, Recharge will dynamically fetch the sku from the corresponding external_platform_variant.
updated_atdatetime
The time the Onetime purchase was last updated.
variant_titlestring
The name of the variant in a shop’s catalog.

The onetime object

{
  "onetime": {
    "id": 16909886,
    "address_id": 21317826,
    "customer_id": 18819267,
    "created_at": "2018-11-14T11:20:05+00:00",
    "external_product_id": {
      "ecommerce": "4950280863846"
    },
    "external_variant_id": {
      "ecommerce": "32139793137766"
    },
    "is_cancelled": false,
    "next_charge_scheduled_at": "2018-12-17T00:00:00+00:00",
    "presentment_currency": "USD",
    "price": null,
    "product_title": "SuperKiwi ONETIME",
    "properties": [
      {
        "name": "grind",
        "value": "drip"
      }
    ],
    "quantity": 1,
    "sku": "TOM0001",
    "sku_override": false,
    "updated_at": "2018-11-14T11:20:05+00:00",
    "variant_title": "Blue star"
  }
}

#Create a onetime

POST/onetimes

Create a new Onetime.

Scopewrite_subscriptions

next_charge_scheduled_at is required unless add_to_next_charge is true. The two parameters cannot be passed together.

Body parameters

address_idintegerRequired
Unique numeric identifier for the address the one time purchase is associated with.
add_to_next_chargeboolean
Instructs to add the Onetime to the next charge scheduled under this Address.
custom_event_attributesarray of objectsNew
A list of up to 10 custom key-value pairs to attach to the Events generated by this request. They are returned in the custom_attributes of those Events.
Show child attributesHide child attributes22 new
- keystringNew
  The name of the custom attribute.
- valuestring · nullableNew
  The value of the custom attribute. Maximum length is 255 characters.
external_product_idobject
Unique numeric identifier of the product in external platform.
Show child attributesHide child attributes1
- ecommercestring
  The product id as it appears in the external e-commerce platform. The external_product_id of the Product record in Recharge, linking a Plan to a Product.
external_variant_idobjectRequired
Unique numeric identifier of the product variant in external platform.
Show child attributesHide child attributes1
- ecommercestring
  The variant id as it appears in the external e-commerce platform. The external_variant_id of the Product record in Recharge, linking a Plan to a Product.
next_charge_scheduled_atdate
This will set the charge date of a new Onetime purchase.
Cannot be used with add_to_next_charge
plan_idintegerNew
Unique numeric identifier of a Plan of the product. When price is not provided, the discount of this Plan is used to calculate the price of the Onetime.
presentment_currencystringNew
The presentment currency of the price. It must match the currency of the Address. Required when price is provided and the currency of the Address is not the store's default currency.
pricestring
The price of the product.
price_manually_setbooleanNew
Set to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge.
product_titlestring
The name of the product.
propertiesarray of objects
List of properties.
Show child attributesHide child attributes22 new
- namestringNew
  The name of the property.
- valuestringNew
  The value of the property.
quantityintegerRequired
The quantity of the product.
skustring
A unique identifier of the item in the fulfillment.
sku_overridebooleanNew
When true, the sku stored on the Onetime is used instead of the SKU of the product variant.
variant_titlestringNew
The name of the product variant.

POST/onetimes

curl -X POST 'https://api.rechargeapps.com/onetimes' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "address_id": 45154492,
  "next_charge_scheduled_at": "2021-12-17",
  "price": 6,
  "product_title": "ABC Shirt",
  "properties": [
    {
      "name": "Color",
      "value": "Blue"
    },
    {
      "name": "Size",
      "value": "Medium"
    }
  ],
  "quantity": 1,
  "external_variant_id": {
    "ecommerce": "3844892483"
  }
}'

Response

{
  "onetime": {
    "id": 156155818,
    "address_id": 45154492,
    "customer_id": 40565990,
    "created_at": "2021-05-24T19:14:25+00:00",
    "external_product_id": {
      "ecommerce": "4950280863846"
    },
    "external_variant_id": {
      "ecommerce": "32139793137766"
    },
    "is_cancelled": false,
    "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00",
    "presentment_currency": "USD",
    "price": "6.00",
    "product_title": "ABC Shirt",
    "properties": [
      {
        "name": "Color",
        "value": "Red"
      }
    ],
    "quantity": 1,
    "sku": "TOM0001",
    "sku_override": false,
    "updated_at": "2021-05-24T19:30:14+00:00",
    "variant_title": "Blue star"
  }
}

#Retrieve a onetime

GET/onetimes/{id}

Retrieve a Onetime.

Scoperead_subscriptions

Query parameters

includestringNew
A comma-separated list of related objects to return in the include attribute of the Onetime. address, customer and customer_entitlements also require the read_customers scope, and charge_activities also requires the read_orders scope.
Possible values
addressbundle_productbundle_selectionscharge_activitiescustomercustomer_entitlementsmetafields
include_deletedbooleanNew
If true, the Onetime is returned even if it has been deleted.

GET/onetimes/{id}

curl 'https://api.rechargeapps.com/onetimes/16909886' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "onetime": {
    "id": 16909886,
    "address_id": 45154492,
    "created_at": "2021-05-24T19:14:25+00:00",
    "customer_id": 40565990,
    "external_product_id": {
      "ecommerce": "4950280863846"
    },
    "external_variant_id": {
      "ecommerce": "32139793137766"
    },
    "is_cancelled": false,
    "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00",
    "presentment_currency": "USD",
    "price": "6.00",
    "product_title": "ABC Shirt",
    "properties": [
      {
        "name": "Color",
        "value": "Blue"
      }
    ],
    "quantity": 1,
    "sku": "TOM0001",
    "sku_override": false,
    "updated_at": "2021-05-24T19:30:14+00:00",
    "variant_title": "Blue star"
  }
}

#Update a onetime

PUT/onetimes/{id}

Update an existing Onetime item.

Scopewrite_subscriptions

Body parameters

address_idinteger
Unique numeric identifier for the address the Onetime Purchase is associated with (cannot be used with next_charge_scheduled_at)
custom_event_attributesarray of objectsNew
A list of up to 10 custom key-value pairs to attach to the Events generated by this request. They are returned in the custom_attributes of those Events.
Show child attributesHide child attributes22 new
- keystringNew
  The name of the custom attribute.
- valuestring · nullableNew
  The value of the custom attribute. Maximum length is 255 characters.
external_product_idobjectNew
An object containing the product id as it appears in external platforms.
Show child attributesHide child attributes11 new
- ecommercestringNew
  The product id as it appears in the external e-commerce platform.
next_charge_scheduled_atdate
This will set the charge date of a new Onetime purchase.
presentment_currencystringNew
The presentment currency of the price. It must match the currency of the Onetime. Required when price is provided and the currency of the Onetime is not the store's default currency.
pricestring
The price of the product.
price_manually_setbooleanNew
Set to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge.
product_titlestring
The name of the product.
propertiesarray of objects
List of properties.
Show child attributesHide child attributes2
- namestring
  The name of the property.
- valuestring
  The value of the property.
quantityinteger
The quantity of the product.
external_variant_idobject
Unique numeric identifier of the product variant.
Show child attributesHide child attributes1
- ecommercestring
  The variant id as it appears in the external e-commerce platform. The external_variant_id of the Product record in Recharge, linking a Plan to a Product.
skustring
A unique alphanumeric identifier of the item in the fulfillment.
sku_overridebooleanNew
When true, the sku stored on the Onetime is used instead of the SKU of the product variant.
variant_titlestring
The name of the product variant.

PUT/onetimes/{id}

curl -X PUT 'https://api.rechargeapps.com/onetimes/16909886' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "quantity": 1
}'

Response

{
  "onetime": {
    "id": 16909886,
    "address_id": 45154492,
    "created_at": "2021-05-24T19:14:25+00:00",
    "customer_id": 40565990,
    "external_product_id": {
      "ecommerce": "4950280863846"
    },
    "external_variant_id": {
      "ecommerce": "32139793137766"
    },
    "is_cancelled": false,
    "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00",
    "presentment_currency": "USD",
    "price": "6.00",
    "product_title": "ABC Shirt",
    "properties": [
      {
        "name": "Color",
        "value": "Blue"
      }
    ],
    "quantity": 1,
    "sku": "TOM0001",
    "sku_override": false,
    "updated_at": "2021-05-24T19:30:14+00:00",
    "variant_title": "Blue star"
  }
}

#Delete a onetime

DELETE/onetimes/{id}

Delete a Onetime.

Scopewrite_subscriptions

DELETE/onetimes/{id}

curl -X DELETE 'https://api.rechargeapps.com/onetimes/16665185' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{}

#List onetimes

GET/onetimes

Returns a list of all Onetime products from store.

Scoperead_subscriptions

When cursor is passed, limit is the only other query parameter that can be passed with it.

Query parameters

address_idstring
Return the onetimes linked to the given address_id.
address_idsstring
Return the onetimes linked to the given comma-separated list of address_ids.
created_at_maxdatetime
Return the onetimes created before the given date.
created_at_mindatetime
Return the onetimes created after the given date.
customer_idstring
Return the onetimes linked to the given Recharge customer_id.
include_cancelledboolean
If true the response will include the cancelled Onetimes as well as the others.
limitstring
The number of results.
Default 50Maximum 250
pagestringDeprecated
The page to show.
Default 1
Page-based pagination has been deprecated but still available to use for pages up to a 100. If you need data past this point, use cursor pagination.
external_variant_idstring
Return the one time purchases linked to the given external platform product variant_id.
updated_at_maxdatetime
Return the onetimes updated before the given date.
updated_at_mindatetime
Return the onetimes updated after the given date.
idsstring
Comma-separated list of one time purchase ids to filter.
cursorstringNew
Return either the next or previous page of onetimes using the next_cursor or previous_cursor attributes in the response.
external_customer_idstringNew
Return the onetimes linked to the customer with the given id in the external e-commerce platform.
includestringNew
A comma-separated list of related objects to return in the include attribute of the Onetimes. address, customer and customer_entitlements also require the read_customers scope, and charge_activities also requires the read_orders scope.
Possible values
addressbundle_productbundle_selectionscharge_activitiescustomercustomer_entitlementsmetafields
include_deletedbooleanNew
If true the response will include the deleted Onetimes as well as the others.
sort_bystringNew
Sort the results by the given attribute and direction. Defaults to id-desc.
Possible values
id-ascid-desccreated_at-asccreated_at-descupdated_at-ascupdated_at-desc

GET/onetimes

curl 'https://api.rechargeapps.com/onetimes?limit=3' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "next": "next_cursor",
  "previous": "previous_cursor",
  "onetimes": [
    {
      "id": 16909886,
      "address_id": 45154492,
      "created_at": "2021-05-24T19:14:25+00:00",
      "customer_id": 40565990,
      "external_product_id": {
        "ecommerce": "4950280863846"
      },
      "external_variant_id": {
        "ecommerce": "32139793137766"
      },
      "is_cancelled": false,
      "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00",
      "presentment_currency": "USD",
      "price": "6.00",
      "product_title": "ABC Shirt",
      "properties": [
        {
          "name": "Color",
          "value": "Blue"
        }
      ],
      "quantity": 1,
      "sku": "TOM0001",
      "sku_override": false,
      "updated_at": "2021-05-24T19:30:14+00:00",
      "variant_title": "Blue star"
    }
  ]
}