API Reference¶

A reference for all of the available API endpoints. Also available in the client documentation:

General Endpoints¶

/index/

Methods: GET

Return the API index which includes general information about the current status of the service.

Example output:

{
 'api': {
        'admin': 'terry@virdocs.com',
        'available_versions': [
        {
            'version': 'v1',
            'version_date': '2014-03-06',
            'version_help': '/v1/describe/',
            'version_major': 1,
            'version_string': '1.0.0',
            'version_url': '/v1/'
        }],
        'current_version': 'v1',
        'host': 'api.redshelf.com'
    },
     'code': 200,
     'success': True,
     'test_mode': False
 }

/profile/

Methods: GET

Return information about your account including access constraints.

Example output:

{
 'code': 200,
 'profile': {
    'address_1': '747 N. LaSalle St',
    'address_2': 'Suite 220',
    'city': 'Chicago',
    'country': 'US',
    'nickname': 'RedShelf',
    'state': 'IL',
    'zip': '60654'
 },
 'scopes': ["book_metadata", "invite_user"],
 'success': True,
 'test_mode': False
}

Book Endpoints¶

/v1/book/<hash>/

/v1/book/isbn/<isbn>/

/v1/book/isbn/<isbn>/pricing/

/v1/book/sku/<sku>/

Methods: GET

Returns information about a specific book when given either a hash_id OR isbn. Information returned may include metadata, pricing, distribution, and white label configuration. If no matching book is found, a 404 code is returned.

GET /v1/book/ccc5a093f5ee30ec749e4909840f0f7b794066bb/

200 OK:

{
  'code': 200,
  'success': True,
  'test_mode': False,
  'book': {
    'id': 876,
    'hash_id': 'ccc5a093f5ee30ec749e4909840f0f7b794066bb',
    'title': 'Test Combo Book',
    'subtitle': 'This is a subtitle',
    'description': 'This is a book description.',
    'author': 'Author name or sequence of names',
    'language': 'English',
    'num_pages': 0,
    'publish_year': None,
    'sample_url': '/book/sample/5/',
    'identifiers': {
        'eisbn10': '1234567890',
        'eisbn13': '1234567890123',
        'hash_id': 'ccc5a093f5ee30ec749e4909840f0f7b794066bb',
        'id': 876,
        'isbn10': '',
        'isbn13': '',
        'parent_isbn': '',
        'sku': ''
    },
    'drm': {
        'copy_percent': None,
        'offline_percent': None,
        'offline_range': '',
        'print_allowance_percent': 0.250,
        'print_allowance_range': '',
        'sample_page_end': 0,
        'sample_percent': None
    },
    'files': {
        'cover_image': {
            'filename': 'default_book_cover.jpg',
            'url': '//content.redshelf.com/site_media/media/cover_image/default_book_cover.jpg'
        },
        'thumbnail': None
    },
    'digital_pricing': [
        {
           'calculated_expiration_date': '2014-05-29',
           'currency': 'USD',
           'days_until_expiration': '78',
           'deactivation_date': '2014-05-29T05:00:00Z',
           'description': 'Rent eBook (until 2014-05-29)',
           'description_limit': '2014-05-29 05:00:00+00:00',
           'id': 932,
           'is_limited': True,
           'limit_days': 0,
           'other_pricing': 'EXPIRATION',
           'price': '2.99'
        },
        {
           'calculated_expiration_date': '2014-04-12',
           'currency': 'USD',
           'days_until_expiration': '31',
           'deactivation_date': None,
           'description': 'Rent eBook (30 days)',
           'description_limit': '30 days',
           'id': 927,
           'is_limited': True,
           'limit_days': 30,
           'other_pricing': 'LIMITED',
           'price': '5.99'
        },
        {
           'currency': 'USD',
           'deactivation_date': None,
           'description': 'Buy eBook (lifetime)',
           'description_limit': 'lifetime',
           'id': 908,
           'is_limited': False,
           'limit_days': 0,
           'other_pricing': None,
           'price': '20.00'
        }
    ],
    'publisher': {
        'title': 'Some Publisher Title',
        'description': 'Publisher Description',
        'is_active': True
    },
    'status': {
        'is_active': True,
        'is_html': True,
        'is_processed': True,
        'is_public': True,
        'is_published': True,
        'is_queued': True,
        'processed_date': '2014-03-12T16:00:22Z',
        'queued_date': '2014-03-12T16:06:01Z'
    }
  }
}

Note: Additional data may be returned for each data point depending on your account permissions.

User Endpoints¶

/v1/user/<username>/
/v1/user/email/<email>/: Methods: GET

Retrieve information for a user.

/v1/user/invite/

Methods: POST

Payload: {“email”: “email@address.com”, “first_name”: “name”, “last_name”: “name”, “label”: “mylabel”}

Create a new user account and send an invitation email to that user with a generated password.

POST /v1/user/invite/:

{
 'request':
    {
        "email": "example@user.com",
        "first_name": "Example",
        "last_name": "User"
    }
}

200 OK:

{
 'code': 200,
 'email': 'example@user.com',
 'message': 'Invitation sent.',
 'success': True,
 'test_mode': False,
 'username': '0d72df20f23558620646fb3ea030f5'
}

If the user already exists. you will receive the following response containing the existing user’s username hash.

400 BAD REQUEST:

{
 'code': 400,
 'message': 'User with email address already exists',
 'value': example@user.com,
 'conflict': True,
 'field': 'email',
 'username': '0d72df20f23558620646fb3ea030f5'
}

/v1/user/

Methods: POST

Payload: {“email”: “email@address.com”, “first_name”: “name”, “last_name”: “name”, “passwd”: “secret”, “passwd_confirm”: “secret”, “label”: “mylabel”}

Create a new user account silently. Password field can be omitted to generate a random password.

POST /v1/user/:

{
 "request":
    {
        "email": "example@user.com",
        "first_name": "Example",
        "last_name": "User"
    }
}

200 OK:

{
 'code': 200,
 'email': 'example@user.com',
 'passwd': u'Y9ivTu%6uH',
 'message': 'User created.',
 'success': True,
 'test_mode': False,
 'username': '0d72df20f23558620646fb3ea030f5'
}

/v1/user/<username>/orders/

Methods: GET, POST

Provides a list of orders the user has made.

/v1/user/<username>/purchase/<purchase_id>/

Methods: GET, POST

Payload: {“refund_data”: false}

POST /v1/user/<username>/purchase/<purchase_id>/:

{
 'request':
    {
        "refund_info": true,
    }
}

Example output:

200 OK:

{
  'code': 200,
  'success': True,
  'test_mode': False,
  'book': {
    'hash_id': 'TOL_book_b',
    'sample_url': 'http://redshelf.com/xxxxx',
    'title': 'TOL_book'
  },
  'digital_pricing': {
    'description': 'Rent eBook (180 days)',
    'id': 5,
  },
  'expiration_date': None,
  'id': 5,
  'is_active': True,
  'is_digital': True,
  'is_print': False,
  'is_refunded': False,
  'purchase_date': '2020-04-23T09:09:41.045Z',
  'purchase_price': '47.45',
  'quantity': 1,
  'refund_available': True,
  'user': {
    'full_name': '',
    'username': 'user1',
  }
}

404 Not Found: Purchase

{
 'code': 404,
 'error': True,
 'test_mode': False,
 'message': 'Purchase not found'
}

Retrieves a single purchase for a user. “refund_data” controls whether the purchase in the response contains the true refund availability of a purchase. If it is set to false, the “refund_available” field in the returned purchase will always be true. The purpose of this parameter is to reduce the response time of this endpoint.

The payload is optional. If you do not need to modify the refund_data parameter, you can simply send a GET request without the payload. If you need to modify the refund_info parameter, you can send a POST request with the payload.

Order Endpoints¶

/v1/order/external/

Methods: POST

Payload: {“username”: “0d72df20f23558620646fb3ea030f5”, “billing_address”: {“full_name”: “Example User”, postal_code=”60527”, country=”US”}, “digital_pricing”: [123], “order_type”, “POSSale”, “org”: “MYCOMPANY”}

Provides a method for reporting orders processed outside of the RedShelf system. This includes orders where the integration partner is using their own checkout and fund collection processes.

POST /v1/order/external/:

{
 "request":
    {
        "username": "0d72df20f23558620646fb3ea030f5",
        "billing_address": {"full_name": "Example User", postal_code="60527", country="US"},
        "digital_pricing": [123],
        "order_type": "APIPartnerPlan",
        "org": "MYCOMPANY"
    }
}

200 OK:

{
    'code': 200,
    'message': 'Order created.',
    'success': True,
    'test_mode': False,
    'order': {
        'id': 5,
        'username': u'0d72df20f23558620646fb3ea030f5',
        'is_complete': True,
        'item_count': 1,
        'items': [
            {
                'order': {
                    'id': 5
                },
                'book': {
                    'hash_id': 'ccc5a093f5ee30ec749e4909840f0f7b794066bb',
                    'title': 'Test Combo Book'
                },
                'user': {
                    'full_name': 'Example User',
                    'username': '0d72df20f23558620646fb3ea030f5'
                },
                'expiration_date': None,
                'id': 98,
                'is_active': True,
                'is_digital': False,
                'is_print': True,
                'is_refunded': False,
                'purchase_date': '2014-02-28T21:30:21.335Z',
                'purchase_price': '12.99',
                'quantity': 1
            }
        ],
        'totals': {
            'subtotal': 12.99,
            'shipping': 5.99,
            'taxes': 0.00,
            'total': 19.80
        }
    },
}

username: The hashed user identifier (required)

digital_pricing: A list of integer IDs for the items being sold; the ID is found in the id field of the pricing dict for each book. (required)

billing_address: The address the address that will be associated with the purchasing order. format: {‘full_name’: ‘Example User’, postal_code=‘60527’, country=’US’} (required)

shipping_address: The shipping address that will be associated with the order if the order is Print On Demand books. (optional)

order_type: The payment plan to be executed with the order. (required)

org: The organization through that is supply the order. (required)

label: the sub-domain of the label associated with the order. (optional)

send_email: A boolean field that indicates whether an email reporting transaction details will be sent to Members of the optionally supplied label. default value: True (optional)

order_number: a unique identifier that will be supplied with the order. (optional and idempotent, max length: 20 characters)

/v1/order/refund/

Methods: POST

Payload: {“order_id”: order_id, “send_email”: send_email}

Provides a method for reporting refunds processed outside of the RedShelf system. This includes orders where the integration partner is using their own checkout and fund collection processes.

The ID is the order ID returned when an order is created. Optionally a list of item IDs from the order information can be supplied for partial refunds.

The refund request may be rejected (403) if it is outside the publisher’s window for acceptable refunds. eBooks are refundable within 14 days of the first day of access, or thirty (30) days after the purchase is made, whichever occurs first. Additionally, RedShelf cannot fulfill refund requests if more than 10% of the product has been viewed and/or if any page(s) of the product has been printed.

The send_email parameter is an optional parameter which allows the restricting or force-sending of an email. If no parameter is applied, then the organization’s api_email value will be applied (default: True). This parameter must be supplied as a string (‘True’ or ‘False’).

POST /v1/order/refund/:

{
 'request':
    {
        "order_id": 1,
    }
}

Code Endpoints¶

/v1/codes/generate/

Methods: POST

Payload: {“hash_id”: hash_id, “org”: org_id, “count”: count, “limit_days”: limit_days, “expiration_date”: expiration_date, “samples”: samples, “label”: label}

Generate codes for end-user book access. The limit_days field controls the number of days from code redemption the user’s access will be available for. The expiration_date field sets a hard date after which user access is disabled.

POST /v1/codes/generate/:

{
 'request':
    {
        "hash_id": "efb237d3edd664c4f81f87d9b27abfa37228e9b3",
        "org":  "MYCOMPANY",
        "count": 3,
        "limit_days": 180
    }
}

200 OK:

{
    'code': 200,
    'success': true,
    'test_mode': false
    'codes': [
        {
            'code': 'XXXXXXXXXXXXXXXX',
            'deactivation_date': null,
            'limit_days': 180
        },
        {
            'code': 'XXXXXXXXXXXXXXXX',
            'deactivation_date': null,
            'limit_days': 180
        },
        ...
   ]
}

Import Endpoints¶

/v1/import/search/

Methods: POST

Payload: {“title”: title, “isbn”: isbn_list, “author”: author, “limit”: limit, “offset”: offset}

Search the list of imported titles. These titles are not available for sale currently but are incoming titles.

POST /v1/import/search/:

{
 'request':
    {
        "title": "college success",
        "limit": 100,
        "offset": 0
    }
}

200 OK:

{
    'code': 200,
    'count': 1,
    'limit': 100,
    'offset': 0,
    'results': [
        {
            'title': 'Cornerstones for Career College Success, 3/e',
            'author': 'Patricia G. Moody, Robert M. Sherfield',
            'publisher': 'Prentice Hall',
            'edition_number': 3,
            'identifiers': {
                'book_id': 0,
                'eisbn10': '032184954X',
                'eisbn13': '9780321849540',
                'isbn10': '0132789353',
                'isbn13': '9780132789356'
            },
            'status': {
                'deleted': false,
                'file_received': false,
                'imported': false
            }
        },
    ],
    'success': true,
    'test_mode': false
}