Subscriptions

>>>

POST /api/v1/subscriptions
Create Subscriptions

Create a new subscription. A subscription represents a recurring payment. Recurring payments may be on a weekly, monthly, or yearly basis, specified by the period parameter.

In order to create a subscription, a customer ID must be supplied. The customer object contains saved payment info, which is regularly charged by the subscription.

A subscription can't be modified once it's created. To change a subscription, you must delete it and create a new one.

Examples

  • cURL
  • Node.js
  • Ruby
curl -X POST https://komoju.com/api/v1/subscriptions \
  -u sk_123456: \
  -d "amount=2000" \
  -d "currency=JPY" \
  -d "customer=4vcs9yqq93fb5s611ebhyulaw" \
  -d "period=monthly" 
var querystring = require('querystring');
var https = require('https');
var secret_key = 'sk_123456'
var auth = 'Basic ' + Buffer.from(secret_key + ':').toString('base64');
var post_data = querystring.stringify({
  'amount': '2000',
  'currency': 'JPY',
  'customer': '4vcs9yqq93fb5s611ebhyulaw',
  'period': 'monthly'
});

var post_options = {
  host: 'komoju.com',
  port: '443',
  path: '/api/v1/subscriptions',
  method: 'POST',
  headers: {
    'Authorization': auth,
    'Content-Length': Buffer.byteLength(post_data)
  }
};

var post_req = https.request(post_options, function(res) {
    res.setEncoding('utf8');
    res.on('data', function (chunk) {
        console.log(chunk);
    });
});

post_req.write(post_data);
post_req.end();
require 'uri'
require 'net/https'
require 'json'
require 'base64'
require 'pp'
uri = URI.parse('https://komoju.com/api/v1/subscriptions')
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
secret_key = 'sk_123456'
auth = Base64.encode64("#{secret_key}:")
headers = {
  'Content-Type' => 'application/json',
  'Authorization' => "Basic #{auth}"
}

body = {
  amount: "2000",
  currency: "JPY",
  customer: "4vcs9yqq93fb5s611ebhyulaw",
  period: "monthly"
}

res = https.post(
  uri.path,
  body.to_json,
  headers
)

puts res.body
{
  "id": "1bv1aplpol3igsp9u9te9sgzu",
  "resource": "subscription",
  "status": "active",
  "amount": 2000,
  "currency": "JPY",
  "customer": {
    "id": 314,
    "uuid": "4vcs9yqq93fb5s611ebhyulaw",
    "merchant_id": 2696,
    "created_at": "2020-06-09T16:41:52.813+09:00",
    "updated_at": "2020-06-09T16:41:52.813+09:00",
    "email": "walkerward@gutkowski.info",
    "currency": null,
    "metadata": {
      "order_id": "abcdefg"
    }
  },
  "period": "monthly",
  "day": 9,
  "payment_details": {
    "type": "credit_card",
    "month": "01",
    "year": "2025",
    "email": "test@example.com"
  },
  "retry_count": 0,
  "retry_at": null,
  "next_capture_at": "2020-07-09T07:41:52Z",
  "created_at": "2020-06-09T07:41:52Z",
  "ended_at": null,
  "metadata": {
  },
  "payments": [
    "9sfa45byqsjswsbq0e6l24r73"
  ]
}

Params

Param name Description
customer
required

The ID of an existing customer in which to provide payment details for the payment. This or payment_details must be present.
amount
required

The amount to be charged before tax. Must be equal or greater than 0, without thousands separator. The amount cannot be a decimal value. For example, for an amount of 10 and currency of EUR, the payment will be 0.10 EUR.
currency
required

3 letter ISO currency code used to pay.
period
required

Interval for subscription payments: weekly, monthly, or yearly
metadata
optional

A set of key-value pairs.
>>>

GET /api/v1/subscriptions
List Subscriptions

List existing subscriptions. Paginates with the usual page, per_page, start_time, and end_time parameters.

Examples

  • cURL
  • Node.js
  • Ruby
curl -X GET https://komoju.com/api/v1/subscriptions \
  -u sk_123456:
var https = require('https');
var secret_key = 'sk_123456'
var auth = 'Basic ' + Buffer.from(secret_key + ':').toString('base64');
var get_options = {
  host: 'komoju.com',
  port: '443',
  path: '/api/v1/subscriptions',
  method: 'GET',
  headers: {
    'Authorization': auth
  }
};

var get_req = https.request(get_options, function(res) {
    res.setEncoding('utf8');
    res.on('data', function (chunk) {
        console.log(chunk);
    });
});

get_req.end();
require 'uri'
require 'net/https'
require 'json'
require 'base64'
require 'pp'
uri = URI.parse('https://komoju.com/api/v1/subscriptions')
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
secret_key = 'sk_123456'
auth = Base64.encode64("#{secret_key}:")
headers = {
  'Content-Type' => 'application/json',
  'Authorization' => "Basic #{auth}"
}

res = https.get(uri.path, headers)
puts res.body
{
  "resource": "list",
  "total": 3,
  "page": 1,
  "per_page": 10,
  "last_page": 1,
  "data": [
    {
      "id": "64lir0fi5z4xfos9szkth62gx",
      "resource": "subscription",
      "status": "pending",
      "amount": 1000,
      "currency": "JPY",
      "customer": {
        "id": 313,
        "uuid": "95s6o99li80x1a7y9srk1rkcz",
        "merchant_id": 2695,
        "created_at": "2020-06-09T16:41:52.617+09:00",
        "updated_at": "2020-06-09T16:41:52.617+09:00",
        "email": "lance@lemkespinka.com",
        "currency": null,
        "metadata": {
          "order_id": "abcdefg"
        }
      },
      "period": "monthly",
      "day": 9,
      "payment_details": {
        "type": "credit_card",
        "month": "01",
        "year": "2025",
        "email": "test@example.com"
      },
      "retry_count": 0,
      "retry_at": null,
      "next_capture_at": null,
      "created_at": "2020-06-09T07:41:52Z",
      "ended_at": null,
      "metadata": {
      },
      "payments": [

      ]
    },
    {
      "id": "4enivatmtr5l36nd0h8512pm4",
      "resource": "subscription",
      "status": "pending",
      "amount": 1000,
      "currency": "JPY",
      "customer": {
        "id": 313,
        "uuid": "95s6o99li80x1a7y9srk1rkcz",
        "merchant_id": 2695,
        "created_at": "2020-06-09T16:41:52.617+09:00",
        "updated_at": "2020-06-09T16:41:52.617+09:00",
        "email": "lance@lemkespinka.com",
        "currency": null,
        "metadata": {
          "order_id": "abcdefg"
        }
      },
      "period": "monthly",
      "day": 9,
      "payment_details": {
        "type": "credit_card",
        "month": "01",
        "year": "2025",
        "email": "test@example.com"
      },
      "retry_count": 0,
      "retry_at": null,
      "next_capture_at": null,
      "created_at": "2020-06-09T07:41:52Z",
      "ended_at": null,
      "metadata": {
      },
      "payments": [

      ]
    },
    {
      "id": "bf38pyacwtcqm3bem932vyefr",
      "resource": "subscription",
      "status": "pending",
      "amount": 1000,
      "currency": "JPY",
      "customer": {
        "id": 313,
        "uuid": "95s6o99li80x1a7y9srk1rkcz",
        "merchant_id": 2695,
        "created_at": "2020-06-09T16:41:52.617+09:00",
        "updated_at": "2020-06-09T16:41:52.617+09:00",
        "email": "lance@lemkespinka.com",
        "currency": null,
        "metadata": {
          "order_id": "abcdefg"
        }
      },
      "period": "monthly",
      "day": 9,
      "payment_details": {
        "type": "credit_card",
        "month": "01",
        "year": "2025",
        "email": "test@example.com"
      },
      "retry_count": 0,
      "retry_at": null,
      "next_capture_at": null,
      "created_at": "2020-06-09T07:41:52Z",
      "ended_at": null,
      "metadata": {
      },
      "payments": [

      ]
    }
  ]
}

Params

Param name Description
start_time
optional

Query for records created after this time.
end_time
optional

Query for records created before this time.
per_page
optional

How many complete objects per page.
page
optional

Page number to query for.
>>>

Show an existing subscription, including its customer and scrubbed payment details.

Examples

  • cURL
  • Node.js
  • Ruby
curl -X GET https://komoju.com/api/v1/subscriptions/0t8yd4nd2ql5ntq2k9dbe0fdk \
  -u sk_123456:
var https = require('https');
var secret_key = 'sk_123456'
var auth = 'Basic ' + Buffer.from(secret_key + ':').toString('base64');
var get_options = {
  host: 'komoju.com',
  port: '443',
  path: '/api/v1/subscriptions/0t8yd4nd2ql5ntq2k9dbe0fdk',
  method: 'GET',
  headers: {
    'Authorization': auth
  }
};

var get_req = https.request(get_options, function(res) {
    res.setEncoding('utf8');
    res.on('data', function (chunk) {
        console.log(chunk);
    });
});

get_req.end();
require 'uri'
require 'net/https'
require 'json'
require 'base64'
require 'pp'
uri = URI.parse('https://komoju.com/api/v1/subscriptions/0t8yd4nd2ql5ntq2k9dbe0fdk')
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
secret_key = 'sk_123456'
auth = Base64.encode64("#{secret_key}:")
headers = {
  'Content-Type' => 'application/json',
  'Authorization' => "Basic #{auth}"
}

res = https.get(uri.path, headers)
puts res.body
{
  "id": "0t8yd4nd2ql5ntq2k9dbe0fdk",
  "resource": "subscription",
  "status": "pending",
  "amount": 1000,
  "currency": "JPY",
  "customer": {
    "id": 315,
    "uuid": "32vg14fz53dkhqalk1qch6pp4",
    "merchant_id": 2697,
    "created_at": "2020-06-09T16:41:53.021+09:00",
    "updated_at": "2020-06-09T16:41:53.021+09:00",
    "email": "conradschumm@robel.net",
    "currency": null,
    "metadata": {
      "order_id": "abcdefg"
    }
  },
  "period": "monthly",
  "day": 9,
  "payment_details": {
    "type": "credit_card",
    "month": "01",
    "year": "2025",
    "email": "test@example.com"
  },
  "retry_count": 0,
  "retry_at": null,
  "next_capture_at": null,
  "created_at": "2020-06-09T07:41:53Z",
  "ended_at": null,
  "metadata": {
  },
  "payments": [

  ]
}
>>>

Delete a subscription. Once deleted, the subscription's regular payments will stop.

Examples

  • cURL
  • Node.js
  • Ruby
curl -X DELETE https://komoju.com/api/v1/subscriptions/41cuy6rxu34lcqbmuf6irxts6 \
  -u sk_123456:
var https = require('https');
var secret_key = 'sk_123456'
var auth = 'Basic ' + Buffer.from(secret_key + ':').toString('base64');
var delete_options = {
  host: 'komoju.com',
  port: '443',
  path: '/api/v1/subscriptions/41cuy6rxu34lcqbmuf6irxts6',
  method: 'DELETE',
  headers: {
    'Authorization': auth
  }
};

var delete_req = https.request(delete_options, function(res) {
    res.setEncoding('utf8');
    res.on('data', function (chunk) {
        console.log(chunk);
    });
});

delete_req.end();
require 'uri'
require 'net/https'
require 'json'
require 'base64'
require 'pp'
uri = URI.parse('https://komoju.com/api/v1/subscriptions/41cuy6rxu34lcqbmuf6irxts6')
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
secret_key = 'sk_123456'
auth = Base64.encode64("#{secret_key}:")
headers = {
  'Content-Type' => 'application/json',
  'Authorization' => "Basic #{auth}"
}

res = https.delete(uri.path, '{}', headers)
puts res.body
{
  "id": "41cuy6rxu34lcqbmuf6irxts6",
  "resource": "subscription",
  "status": "deleted",
  "amount": 1000,
  "currency": "JPY",
  "customer": {
    "id": 316,
    "uuid": "5qpkpiu9nylaqhron4fa12ryz",
    "merchant_id": 2698,
    "created_at": "2020-06-09T16:41:53.151+09:00",
    "updated_at": "2020-06-09T16:41:53.151+09:00",
    "email": "marccorkery@mcdermott.biz",
    "currency": null,
    "metadata": {
      "order_id": "abcdefg"
    }
  },
  "period": "monthly",
  "day": 9,
  "payment_details": {
    "type": "credit_card",
    "month": "01",
    "year": "2025",
    "email": "test@example.com"
  },
  "retry_count": 0,
  "retry_at": null,
  "next_capture_at": null,
  "created_at": "2020-06-09T07:41:53Z",
  "ended_at": "2020-06-09T07:41:53Z",
  "metadata": {
  },
  "payments": [

  ]
}